This report describes a general-purpose Requirements Specification Language, SpecL. The purpose of SpecL is to specify precisely the external structure of a mechanized system, and to define requirements that the system must meet. A system can be comprised of a mixture of hardware, software, and human processing elements.

SpecL is a hybrid of features found in several popular requirements specification languages, such as SADT (Structured Analysis and Design Technique [Ross 77]), PSL (Problem Statement Language [Teichroew 77]), and RMF (Requirements Modeling Framework [Greenspan 82]). While languages such as these have useful features for structuring a specification, they generally lack formality. To overcome the deficiencies of informal requirements languages, SpecL has constructs for formal mathematical specification. These constructs are similar to those found in formal specification languages such as EHDM (Enhanced Hierarchical Development Methodology [Rushby 91]), Larch [Guttag 85], and OBJ3 [Goguen 88]. The formal features of SpecL need not be used in all situations. A requirements specification can be constructed in a number of levels from informal, to semi-formal, to fully formal. Examples to follow will illustrate these levels.

The reader of this report is assumed to be familiar with concepts of computer programming, as well as concepts of discrete mathematics. No familiarity with the requirements analysis or formal specification is assumed. While the report is primarily a reference manual for the SpecL language, it does include tutorial discussion and examples on the concepts of requirements specification.

1.1. The Overall Structure of a Requirements Specification

In SpecL, a requirements specification consists of two parts: an object- oriented specification, and a operation-oriented specification. Dividing a specification into these two parts promotes the concept of multiple system views. One view focuses on the system from the perspective of the data objects, the other from the perspective of the functional operations. Neither view is the correct one -- they both convey the same meaning in different ways. Depending on the natural orientation of the system being specified, one form of view may be the more natural. Specifically, for so-called "transaction-oriented" systems, the object-oriented view is typically more natural. Conversely, for "transform-oriented" systems, the operation-oriented view is typically the more natural.

A transaction-oriented system is characterized by a large object on which relatively small, incremental operations are performed. A database management system (DBMS) is a good example of a transaction-oriented system. In a DBMS, a typically large database object is incrementally modified by relatively small operations to add, delete, and search for database entries. The DBMS operations are often referred to as transactions, and hence the system is referred to as transaction-oriented.

A transform-oriented system is characterized by relatively large operations that perform major transformations on objects. A report generation system (RPGS) is a good example of a transform-oriented system. In an RPGS, a large input object, such as a database, undergoes a major transformation to produce a large output object -- the report. As the name suggests, a transform-oriented system performs a major transformation on its input, such that the resulting output is substantially different in structure from the input. This is in contrast to a transaction-oriented system, in which the output is the result of a relatively small change to the input, and the input and output have much the same overall structure.

Whichever is the more natural view, an SpecL requirements specification should always contain both. That is, if a system is primarily viewed as object- oriented, it will still contain an operation-oriented view. Conversely, a primarily operation-oriented specification will also contain an object-oriented view. In this way, the two views provide a form of cross checking on specification consistency and completeness. Something that may have been overlooked in the object-oriented view may arise naturally in the operation- oriented view, and vice versa. When complete, the pair of views provides the separate parts of a mutually consistent requirements specification.

1.2. Underlying Principles

SpecL, and similar languages such as RMF and EHDM, share a number of common underlying principles. These principles include:

1. Object/Operation Model -- a specification is comprised fundamentally of two forms of entity: objects and operations; these entities have well-defined relations to one another.
2. Hierarchy -- the primary relation between entities of the same type is hierarchy; that is, an entity is composed hierarchically of subentities, which may in turn be further hierarchically decomposed.
3. Input/Output Relationships -- the primary relation between objects and operations is input/output; specifically, operations take objects as inputs and produce objects as outputs.
4. Attribute/Value Pairs -- in addition to relations to other entities, an entity may have other general attributes that further describe its properties and characteristics.
5. Five Composition Primitives -- when an object is decomposed into subentities, five composition forms can be used; the forms are:
   1. and composition: an object is composed as a heterogeneous collection of subentities
   2. or composition: an object is composed as a selected one of a heterogeneous collection of subentities
   3. repetitive composition: an object is composed as a homogeneous collection of zero or more subentities
   4. functional composition: an object is composed as a function from input objects to output objects
   5. recursive composition -- an object may contain itself as a subobject
6. Class/Subclass/Instance Composition -- a secondary form of hierarchical relation is that of class/instance; an object class defines a generic object template; an object subclass or instance specializes the generic class by adding additional attributes.
7. Object/Operation Duality -- the composition and relational forms apply equally to both objects and operations; that is, both objects and operations can be decomposed hierarchically, with general attribute/value pairs, and defined as classes.
8. Strong Typing -- all objects in a specification define a formal type; SpecL formulas and expressions are type checked to confirm that object names are used in type-correct contexts.
9. Functional Operations -- all operations are fully functional and side effect free; an operation may only access explicit input objects, and may effect change only through explicit output objects.
10. Declarative Specification -- a specification declares structure and function without specifying operational details.

It is possible to use SpecL to specify a system on a number of levels. The most typical use of SpecL is to define user-level specifications. Here the term user refers to the ultimate end-user of a system being specified. Hence, a user-level specification is one in which all objects and operations are directly accessible to an end-user.

The general guideline for developing user-level specifications is that if an end-user does not need to know about an object or operation, then that object or operation should not appear in a specification. The purpose of this guideline is to keep an SpecL specification as free as possible of implementation detail. As a specification language, SpecL should be used to define what a system does, not how the system works.

For most systems, the dividing line between what an end-user does and does not need know is reasonably clear. As an example, consider the specification of two different mechanized systems: an automobile and a database management system. Table 1 summarizes what objects and operations end users should know about in these two systems.

The table illustrates the spectrum of information an end-user needs to know. It is clear that an end-user absolutely needs to know about the basic objects and operations of the mechanized system. These basics are the objects and operations specifically intended to be the interface between the end-user and the system itself. In the case of an automobile system, the basics include the doors, steering wheel, keys, etc. Basic user-level operations include starting the car, driving it, and stopping. In a computerized DBMS there are comparable user-level objects and operations. The objects include the database records, and the record fields such as name, address, etc. DBMS user-level operations include adding, deleting, and searching for a record.

In addition to basic objects and operations, it is frequently necessary for end users to be aware of certain system properties. The table shows examples of such user-level properties. For the automobile, the user should probably be aware that the automobile uses unleaded fuel. For the DBMS, the user should probably be aware that duplicate records cannot be entered into the database. It is conceivable that a very naive or uninformed user could avoid knowing such properties of a system. Hence, the table indicates the user "probably" should know. At any rate, the system specification should include these as user-level information, whether or not a user chooses to know the information.

The next entries in the table exemplify information that the end-user probably need not know. The example in this category for the automobile is the fact that the automobile uses spark plugs. For the DBMS, the example is that the database uses an ISAM format (Indexed Sequential Access Method). Such information is more appropriately directed to the system maintainers rather than end users. It is implementation-level in nature.

It might be argued that end-users should know information in the "probably not" category on the grounds of performance. That is, an end-user may better understand how the system will perform if certain internal details of the system are made known. However, it is more appropriate that performance information be stated in terms that leave out implementation detail. For example, specifying that the DBMS uses ISAM may indirectly help a knowledgeable end-user know which forms of query operation will be efficient and which inefficient. However, many end-users may not understand at all what ISAM formatting means. It would be better to omit the ISAM detail from the user- level specification altogether. The specification should rather define operation performance properties directly in terms that all end-users can understand. For example, searching for a record by key 1 will take less time than searching for the same record by key 2.

The last entry in the comparison table above indicates information that clearly need not be known by an end user. Such information relates to low-level system implementation details that end users need never be aware of.

1.4. Relationship between an SpecL Specification and a Concrete User Interface

Relating an SpecL specification to a concrete user interface is another means to determine what is appropriate user-level information. Specifically, any user-level object or operation should be directly visible in the user interface. Objects appear in the interface as any visible data values. These include data that are displayed on a screen, in a hardcopy form, or stored in some user-accessible data file. Operations appear in the interface as any form of user command. In concise terms, an operation is invoked as the result of some gesture that is performed by the user. Gestures include keyboard typing, selecting from a mouse-oriented command menu, or pressing a function button with a mouse or other pointing device.

All objects and operations should be traceable to a concrete user interface. However, this does not mean that an SpecL specification should define concrete interface details. In fact, SpecL specifications should be free of interface details. It is intended that SpecL be used to define abstract user-level specifications, for which any number of concrete interfaces may be defined.

Consider the DBMS example above. An SpecL specification will define the abstract structure of the database and record objects, as well as the abstract input/output behavior of the database operations. Given this abstract specification, a number of concrete interfaces could be defined. For example, a text-command interface would define concrete names for the operations, such as "add", "del ", "search". A typical search command could be typed in as follows:

add Name=Smith, Age=25 to DB5

A quite different form of window-based interface could also be defined for the same abstract DBMS specification. In such an interface, the "add", "del", and "search" commands could be pull-down menu selections. The equivalent of the above text command would involve a pull-down gesture sequence to select "add" from the command menu. This would be followed by information entry in some dialog window that would appear in response to the command menu selection. While selecting "add" from a pull-down menu is concretely different than typing "add ..." as a text command, both concrete interface commands correspond to exactly the same abstract operation, namely AddRecord.

An indication that a specification contains inappropriate interface detail is the appearance of objects with names such as "CommandLineText" or "PullDownMenuItems". Such objects should not be in a specification if they refer to the details of a particular style of concrete interface.

In summary, an SpecL specification should be an abstract, user-oriented definition of a system. The specification should be free of implementation detail in any form. The specification should also be free of concrete user interface details.

1.5. Defining Specifications for Embedded Systems

A so-called embedded computer system is intended to exist within some other engineered environment. Embedded systems are frequently characterized by little or no interaction with a human end user. The guidance system for a autonomous vehicle is a good example. In such systems, the preceding guidelines for user-oriented specification must be considered in a different light.

For embedded systems, the "users" are those external components of the surrounding environment with which the embedded system must interface. Identification of "external" may be somewhat more subjective in an embedded system, without the specific focus of a human user. However, the general guideline for embedded system specification is the same as discussed above. Namely, the requirements specification should define the externally visible objects and operations, for some appropriate definition of externality.