Making systems - 36: Specifications

XXX add section on theory of specification [McNamara22]

36.1 Purpose

A system or component specification sits between its concept (Chapter 34) and its design (Chapter 40). The specification is more formal than the concept, but more abstract than the design (which is in turn more abstract than the implementation).

Specification is about recording how a component (or system) should behave or the structure that the component should present. It only documents how the component appears from the outside, as a black box; it does not specify how the component achieves these ends.

There are many ways to express specifications, and many projects use multiple forms together. Most people are familiar with requirements (Chapter 37), but those are only one form and are appropriate for one part of a component’s specification.

XXX make sure this ties into the broader flow of phases

A specification provides a simplified and abstract view of a component. This abstract view allows one to reason about how the component will work with other components. Without the abstract view, one would have to analyze the details of a component’s implementation to determine whether it will interact properly with another. While that is possible, the work of figuring out how the component will behave only serves to reconstruct design information that was originally worked out when designing the component. The reconstructed information will not necessarily match the information used during design, and the effort is wasteful.

A good specification records the intent and assumptions that went into working out what the component is supposed to do. This information helps the component’s implementer and designer to check that they understand what they need to build, and to check that the specification matches the intent. These assumptions also help people understand how a component might need to change when part of the system is redesigned—to add a new feature, for example. A record of the intentions helps people who come along later to understand the system, and the particular component’s role in it.

Finally, a specification serves as a sort of contract between a component and the rest of the system in which it functions. The people building the component in question can proceed to work on their component with confidence that the result will likely integrate correctly into the system as long as they build to that contract. The people building other parts of the system can likewise proceed with reasonable confidence that when they go to use the component, it will do what they expect.

36.1.1 Good specification properties

A specification is used for several different tasks by different people over the course of a project. A good specification needs to be structured and contain the information needed to support these people.

Specifications should be clear and unambiguous. Each of the people who will read and use each specification need to come to the intended meaning of the specification.

They should be testable. Someone using the specification should be able to look at a design or implementation and determine whether it is compliant with the specification. That does not mean that determining compliance is easy; it only means possible. Sometimes the most that is possible is to build a body of evidence that a design is highly probably compliant. For a specification to be testable, however, the specification can’t contain statements like “approximately” or “fast” or “heavy”; it needs specific values that define what “approximately” (“+/- 10%”), fast (“at least 20 m/s”), or heavy (“greater than 5 kilograms”) mean so that compliance is not a matter of subjective judgment that can differ between two different people.

The specifications need to be organized. A specification is no good if the people who need to use it don’t know it exists or can’t find it. A specification is also not useful if the people who need it can’t tell whether it is currently applicable, outdated, or a speculative proposal. Specification should be kept in one place where everyone on the project can find all of them, and they should be maintained under configuration management.

A good specification is minimal. It addresses the needs for the system or component that have been identified in the concept work leading up to the specification, but it does not add other elements that are not relevant to the identified needs. (Note, however, that the process of developing a specification can often reveal needs that were missed in building up the concept. When those gaps are found, the concept need to be updated as well as addressing the gap in the specification.)

36.1.2 Specification versus documentation

Specification and documentation play different roles. Specification is a record of what something should be, while documentation is a record of what it has been designed and implemented to actually be. Specification deals with the black-box, external behavior, while documentation deals with the internals of the component. The documentation should connect decisions about the component’s internal structure to the external behavior or structure documented in the specification.

36.1.3 Specification needed to scale a project

A small project, implemented by a very small group of people over a short time and thereafter left alone, and that does not provide safety- or security-critical functions, does not necessarily need specification.

Unless all of those conditions hold, some level of specification is necessary in order to communicate between people and across time.

The communication includes:

Between those who design the system at large and those who design and implement a specific component. The specification allows different people to work on different parts of the system, which in turn allows a larger team to do the work, and allows some of the work to proceed in parallel.
Between those who design and implement a component and those who verify its correct behavior. The specification defines the “correct behavior” that verification checks.
Between the original designer and someone who must adapt part of the system later (for a new feature or to fix a problem)—bearing in mind that those may be the same people, but later in time when the details are likely to have been forgotten. The specification conveys a simplified, abstract version of what a component is supposed to be, so that the designer making changes can work out how the behavior should change and so that they can work out whether the changes will likely integrate correctly to address the new feature.
Between the system designers and implementers and those who later inspect the system as part of safety or security incident response. Accident response relies on being able to reconstruct both what happened in an incident and what was supposed to happen. This reconstruction is part of determining what changes need to be made to ensure that similar accidents do not recur, and it is also part of working out how to repair things after an incident (when that is possible).

Sidebar: The role of experience substituting for specification

Every specification is written in terms of some level of common knowledge: language, jargon, or subject matter. When writing a specification, one strikes a balance between what is assumed and what is explicitly recorded. Formally, it is not possible to truly fully specify something because that specification is always based on some amount of shared axiomatic knowledge. Such formal specifications also become difficult to understand as the detail overwhelms clarity. At the same time, assuming too much leaves room for misunderstanding.

In small and fast-moving teams, there is a temptation to rely on experience rather than writing down needs, especially when the same person specifies and implements a component. This can work in the short term—but not in the long term, as people change or other people start to share the work. Leaving needs implicit rather than documenting them also disadvantages early career engineers: they do not yet have the experience that would fill in the gaps, and if they cannot do some guided design or implementation work they will not get the experience they need to do more on their own later.

Leaving needs implicit can be okay if it is a transient condition, and needs, specifications, and assumptions are recorded before they are forgotten.

36.2 Theory of specification

36.3 Specifications and systems

A specification defines the metaphorical shape that the component should have in order to fit into and support the system.

A specification treats the component as a black box: it considers only how the component should be seen from the outside, without determining how the component’s internals should be designed or implemented. One way to look at the specification is that it defines a contract between the system and the component: if the component behaves according to the specification, the system should work correctly as a whole.

A specification may define behaviors or attributes that in effect narrow the range of possible designs, possibly to only a single design. That situation in itself does not make a specification invalid. However, the specification should not include definitions that are not strictly needed to record needed external behaviors solely in order to constrain the design.

After a component has been specified, design of the internals of that component begins. The internal design often uses sub-components. The designers will develop specifications for the sub-components.

This process repeats recursively to lower and lower components, until one reaches components that have no further sub-components. The result is a tree (or possibly a DAG) consisting of alternating layers of specifications and designs. (This has been called the “layer cake model”.) The design of one component (or the system) responds to its specification. The specification for subcomponents depends on the design that has been selected for the component—the design determines both what subcomponents there are, and how they are to work together.

36.4 Example

Some years ago, I worked on a rack-mounted computing system that had high reliability and uptime goals. A decision was taken to include a battery pack in each server assembly, so that if the mains power went out the servers would have enough time to record their state on storage before shutting down.

Consider the specification for the battery pack. It may seem simple—provide enough power to run the server assembly for some period of time—but the actual specification contains several subtle elements because its function is entwined with other system-wide reliability and safety behaviors.

Here are some of the system behaviors that affect the specifications for the battery pack:

Keep the server assembly running for long enough to save state to storage and perform an orderly shut down
The server assembly must be able to change its behavior when the battery pack does not have enough energy stored to safely shut down
A server assembly should function correctly for at least X years before needing replacement
When a server assembly is developing a condition that suggests a component will fail soon, the server should detect the likely failure and initiate a repair call
The server assembly must be safe and convenient for a customer to assemble (if needed) and install
The server assembly must not cause a fire, release toxic gasses, or cause other similar harms (which references a safety standard defining the harms to be avoided)
The server assembly must not be vulnerable to supply chain attacks, such as substituting unapproved components, in the period between manufacture and installation at a customer site
The server assembly must fit into a standard 19” computing rack (which references a mechanical standard specification)
The server assembly is intended to operate in a data center environment (which references an environmental specification)

These are rough objectives for the server assembly as a whole. These translate into specifications on the battery pack itself.

Addressing keeping the server assembly running:

The battery pack must provide power at X volts and Y current for at least Z minutes when mains power stops providing power to the server assembly
The voltage and current must be maintained within X of these reference values
The battery pack must provide connectors to deliver and receive electrical energy to and from other components in the server assembly

Addressing the server assembly changing its behavior:

A management system attached to the battery pack must be able to determine when the battery pack state of charge is sufficient to meet the voltage, current, and time need, and when the state of charge is not sufficient ⇒ The battery pack must provide information that allows accurate estimation of its state of charge (e.g. having an accurate relation between voltage and state of charge)
A management system must be able to account for temperature and battery age in making this determination ⇒ The battery must have predictable changes in behavior as temperature and age change

Addressing the server assembly lifetime:

The battery pack must not degrade its storage capacity more than X% over Y years
The battery pack must support a management system detecting when the storage capacity degradation is approaching a level when battery pack replacement will be needed

Addressing likely failure:

The battery pack must exhibit behaviors that allow a management system to detect degradation or incipient faults, such as failure of one battery cell or overheating
The battery pack must have identification that allows batteries from the same manufacturer and manufacturing lot to be tracked for common failure patterns

Addressing safe and convenient customer installation:

The battery pack should be shipped discharged
The battery pack should be safe to handle without protective equipment as long as its case or assembly is not damaged or modified
The battery pack should not make the server assembly too heavy for one person to lift safely
The battery pack, if separately installable, must not have error-prone cabling that a customer might hook up the wrong way

Addressing fire, toxic gasses, and similar safety issues:

The battery pack should be sealed against emissions up to at least X internal pressure
The battery pack should be able to handle up to X impact without taking damage that would lead to thermal or mechanical failures
The battery pack should provide sufficient information to a management system that the management system can disconnect the battery when a failure is beginning, and so that the management system can trigger external safety systems

Addressing supply chain attacks:

The battery pack must be handled only by trusted employees and agents of the company from manufacture to installation
The battery pack must include identifying information that is hard to falsify or replicate

Addressing fitting into a standard rack:

The battery pack must weigh no more than X kilograms
The battery pack must occupy a volume no greater than X by Y by Z millimeters
The battery pack must connect to the rest of the server assembly using X brackets

Addressing the environmental conditions:

The battery pack must function nominally in a given temperature, air pressure, humidity, air gas composition, and dust environment

These example objectives are not all of what would be needed for a server battery pack, but they illustrate several of the kinds of concerns that the battery pack’s designers will need to consider. These rough objectives must be turned into more precise specifications in order to guide the designers accurately. For example, some of the statements above use subjective words like “nominally” that need to be made precise. Other statements are too general and need to be decomposed into a set of more specific statements.

36.5 Kinds of specifications

“Specification” is a deliberately broad term, encompassing many different ways of recording what something should be or do (and why).

Many people assume that “specification” means “requirements”. While requirements are one kind of specification, they are not the only one—and requirements are not generally sufficient by themselves to record all the information needed about behavior or structure.

Kinds of specification include:

Scope or environment. This is a specification of the boundary for a component (or system) Section 6.3 and, therefore, what is inside and outside of the component (or system). The nature of the environment can be seen as a statement about interfaces, it is usually a good idea to document this explicitly. XXX say more about scope below
Requirements. These are short prose statements about what is expected of the component. These statements have the advantage that they have all the flexibility of written language. A reader only needs to know normal language and the associated technical jargon to understand the meaning of the statement. Requirements also have the advantage that they are easily organized and identified in an outline or table form, so that one can trace through each individual statement. Requirements inherit the disadvantages of written language that lead people to devise other notations or diagrams.
Interfaces. While a specification is in general a definition of the overall interface between a component and the system around it, in many domains part of the specification is gathered into an interface (often recorded in an Interface Control Document). A software application programming interface, which defines data structures, function calls, and communication steps used to communicate with a component, is one example. An environmental specification is another example that specifies the heat, vibration, atmosphere, electromagnetic radiation, dust, and other environmental conditions that a component must handle correctly.
Models. These are (semi)formal expressions about structure or behavior, written in a specialized notation or diagram. These expressions have the advantage of being able to express needs that are not easily expressed in prose, such as physical or temporal relations, or mathematical statements. These have the disadvantage that readers often have to learn new notations in order to understand what the expressions mean. Many notations do not lend themselves to easy enumeration of each individual condition that the component should comply with.

There are many kinds of models.

Mechanical models show the physical interface that the component should support. This can be as simple as a volume in which the component must fit. It might include connectors for how the component is attached to other components in the system. More advanced models might include the forces that may act on the component, and how the component must pass those forces from one place to another, or how a component may deform in response to forces.
Mathematical models document how a component behavior should respond to outside inputs, expressed as mathematical formulas. This can range from a simple linear response to an input to a complex and stateful impulse-response model. Many of these are expressed on a continuous time domain.

u(t)=K_{p}e(t)+K_{i}\int_{0}^{t}e(\tau)d\tau+K_{d}\frac{de(t)}{dt}

Example: control function for a PID controller XXX

Behavioral models document how the component will perform sequences of output actions in response to inputs. Many of these models are expressed as diagrams: state machines, sequence or activity diagrams, or timelines. Some models, such as state machines, express all the possible sequences of behavior that could happen; other models, such as sequence diagrams, express one or a few specific sequences without being exhaustive. Many of these models operate on a discrete time domain.

Example: TCP session opening state machine XXX

Domain-specific models. These express needs that are specific to some problem domain, and that are not easy to express in one of the other kinds of models. For example, Earth-orbiting spacecraft typically have an orbit specification, which can be used to determine where the spacecraft will be at various times in the future and what the conditions will be at those times. A material specification might include parts of the phase diagram for the properties of the material at different temperatures and pressures, indicating some conditions in which the material must be solid or gas. Most domain-specific models have an underlying mathematical definition, but the needs can be expressed more clearly using the domain-specific notation rather than only using the underlying formulas.

36.5.1 Combining multiple kinds of specification

In practice I have found that no one kind of specification meets all needs, and have used multiple kinds of specification together.

Generally, each kind of specification we use meets the good specification objectives of being clear and testable, as defined earlier.

Mixing multiple kinds of specification, however, requires care in organizing the specifications. Different kinds are often written and stored in different tools (a tabular tool for requirements; a CAD tool for mechanical drawings). This easily leads to a situation where a practitioner cannot find all of the specifications to which they need to be paying attention.

One way we have addressed this is to use a table of textual requirement statements as a primary specification, and include requirements like “the component shall comply with state machine X”, including a reference to the drawing of the state machine. Using a tool that makes all these forms accessible through one common user interface helps make this convenient for users. Using tools that can perform configuration management across all the different forms of specification also helps.

36.6 Using specifications in a system

We first look at how specifications are developed and used from the outside: from the perspective of those who are concerned with how a component fits into the system, and not with what the specification means for the design internal to a component.

A specification for a system derives from the objectives and concept developed during the system concept development phase.

The system-level specification leads, in turn, to a system design and then recursively to the concepts and specifications for components in the system.

36.6.1 Building the specification

This is the first step in using specifications. The specification developer looks through all of the conceptual material assembled for the system or for a component, and organizes and formalizes it to make a specification.

In practice this does not happen all at once. People develop the various kinds of objectives that lead to the specification iteratively, and parts of the specification will be developed as the objectives and concept becomes clear. As people develop the specification, they will identify gaps in the concept, which will lead to improvements in the objectives and concept and in turn lead to updates to the specification.

36.6.2 Evolving the specification

The needs that a system solves change over time. New capabilities get requested. Regulations evolve. Problems with the system are found and need to be fixed. All of these can lead to changes in the concept and thus to changes in the system specification.

The concept and design of components also changes, and for similar reasons. As well, a component may have a perfectly adequate design, but it may become outdated because subcomponents become unavailable. This leads to a redesign of a component, inducing new specifications for subcomponents.

It is important to follow an organized process when a specification changes. Many process standards recommend specific approaches; for example, ISO 26262 [ISO26262] specifies that any change to a system must begin with an impact analysis, which determines how a change to objectives or specification propagates through the design of the system, and downward through the hierarchy of components. Standards like that also specify that the specifications and designs be maintained under configuration control so that everyone can know whether a change is a work-in-progress proposal or has been committed to.

36.6.3 Validating the specification

The specification must reflect all of the needs identified in the concept from which it derives, and the specification must not add needs that do not appear in the concept and objectives. Before a specification can be declared complete, someone must go through all the material in the concept to check that the specification accurately reflects each of the identified needs or objectives.

A specification validation exercise can also help identify gaps in the objectives. Checking the specification often involves someone who was not part of developing the objectives and concept; a fresh perspective can lead to asking questions about the objectives or the specifications that in turn lead to discoveries of topics that are missing.

36.6.4 System consistency

As the system design grows and more and more components are defined and specified, someone needs to check that the designs and specifications are all consistent. This is especially important for “long distance” dependencies: where the correct function of one component depends on the correct function of another component in a different part of the system. (More formally, when two components A and B depend on each other for correct function, and the lowest common parent of A and B in the component hierarchy is near the top of the hierarchy.)

36.6.5 Safety and security design

As we will discuss in future chapters ! Unknown link ref, the safety and security properties of a system must be designed top down, and they need to be defined early in system development, before too many low-level components are designed.

We advocate using the systems safety methodology ! Unknown link ref, which emphasizes starting with the accidents or losses that are to be avoided, and then the conditions that must be maintained in a system to achieve safe operation. (This is different from many safety methodologies, such as functional safety, which focus on safety in the face of failure conditions and do not address safety problems arising from design or component interactions.) The categories of losses come from the safety and security objectives defined in the concept development phase.

Some example conditions:

A spacecraft must not perform any propulsive maneuvers, emit radio frequency radiation, or perform any physical deployments within 1 km of the upper stage vehicle from which it was deployed. (This example is based on real launch vehicle safety requirements.)
A planetary lander must maintain engine thrust until it has touched down on the surface. (This example is based on the accident analysis of the Mars Polar Lander spacecraft; see ! Unknown link ref for details.)
An autonomous aircraft must not take operational commands from an unauthorized source.

Once these conditions are identified, systems engineers must determine how to address them in the design of the top-level system. They must then create derived specifications for each of the top-level components in the system, and show that if each of the components meets its specifications the overall system will exhibit safe or secure behavior by complying with the safety and security conditions. This process is repeated through at increasingly lower levels of the system.

36.6.6 Review and approval

A specification guides the design and implementation of parts of the system. Given the importance of this role, a specification—or an update to a specification—should be reviewed before being committed to. Each specification should be checked by the people whose work it affects: system designers, the designer of the component or system that contains the thing being specified, potential implementers, and those people who are working on components that will interface with or use the component being specified.

As with other system artifacts, a specification or specification update should be under configuration management so that each user can determine whether they are using the correct version or not, and whether the version they are using is a proposed or work in progress version, is the current approved (baselined) version, or a version that has become obsolete.

36.7 Using specifications for a component

We now turn our attention to those people and activities who use a component to design and implement a component; that is, who are concerned with how the internals of a component reflect its specification.

There are two tracks of activity that use a component’s specification:

One track follows the design and implementation of the component itself, which should result in a component that complies with the specification. The other track follows the design and implementation of verification methods, such as tests or static analyses. The tracks come together when the implementation gets checked by the various verification methods, resulting in a determination of whether the implementation is in fact compliant, or whether the design and implementation need to be fixed to bring it to compliance.

36.7.1 Learning about a component

A specification is an abstracted view of what a component should be. That makes it useful as a guide for someone who needs to learn about a component, before diving into the design or implementation of that component.

Someone who is learning about a component—or about the structure of the system across many components—needs to be able to find the relevant specifications. The specifications should be organized to support them:

Components should have names or identifiers
Specifications should be stored in a repository that allows people to find a specification by its component id, or be able to navigate through the structure of the system to discover information about components
Users should be able to start their search in a single place, well-known to all the team, without having to discover multiple tools that might or might not be readily apparent to new team members

36.7.2 Designing and implementing to specification

The general task of a designer or implementer is to create a component that complies with its specification. In practice, of course, this is a complex activity.

The designer needs to be able to clearly identify all of the behaviors or capabilities that the component must implement. This implies that the specification must be organized in a way that helps the designer find all of these, and in a way that can serve as a checklist for tracking which features have been satisfied and which have not yet.

As we will discuss further in upcoming chapters, the designer or implementer should be able to identify which aspects of the component have the highest design risk or are the most technically complex. The designer and implementer will often choose to focus on these hard aspects first, before dealing with aspects that are easy to solve. The hard aspects are often candidates for prototyping, in order to determine if a design approach is feasible and can meet the specification. (See XXX for more on prototyping and risk reduction.)

Complex systems and components can benefit from the combination of incremental development and continuous integration. Incremental development involves selecting a few parts of the component’s specification and implementing those, followed by testing. Once those aspects of the component appear sound, the developers perform a second iteration by selecting a few more aspects of the specification and adding them to the design and implementation. Continuous integration, in this context, involves performing integration testing of these partial designs and implementations in a skeleton of the rest of the system. The partial implementation of this component may use mockups of subcomponents, or interact with mockups of peer components in the system. We discuss incremental development and continuous integration more in XXX.

As people work through design and implementation, they are likely to find problems or gaps with the specification. The specification may be ambiguous in some part, or the specification may not define the behavior for some condition. The developers must be able to work with those who defined the specification to sort out these issues. The developers should check the specifications in depth, asking the specifiers questions to check their understanding or to confirm that there are issues. The developers then should work with the specifier to resolve the issues.

The developers should not make an assumption about a gap or ambiguity and move forward without confirming their assumption. The people who wrote the specification are responsible for ensuring that the specifications for different components are consistent and address large-scale safety or security concerns. The behaviors needed to support correct interaction are encoded in the specification. The developers are responsible for implementing components that correctly support these behaviors so that the resulting system works correctly. The developers do not necessarily have the big-picture perspective to make changes to these critical behaviors, and do not necessarily know who else needs to know about an assumption in how a component is defined. The developers need to work collaboratively with those responsible for the specifications so that all the pieces of the system remain consistent and correct, and so that everyone involved shares a common understanding of how the components and system are to function.

A component’s implementation will need to be verified against the component’s specification. People using continuous testing or test-driven development methods have had good results producing correct component implementations efficiently by testing an implementation in small increments as functionality gets added to it. This reduces the risk that the design or implementation has made some fundamental, early mistake that becomes increasingly expensive to correct as more functionality is implemented on top of the erroneous implementation. Performing continuous testing (or verification) requires having verification cases defined and implemented concurrent with the implementation of the corresponding functionality.

Finally, each component design and implementation will need to be reviewed and approved before being accepted as finished. Verifying that the design and implementation comply with the specification is a major part of the review process. The review activities will be much easier if the specification is well organized.

36.7.3 Evolving specifications

As mentioned earlier, a component’s specification will likely change when a system remains in use for a long time. Systems engineers will need to investigate the impact of making a change to a specification before committing to the change.

The component designers and implementers are part of the investigation process. While a systems engineer can look at what will change in how a component interacts with other parts of the system, the component designers and implementers are better positioned to evaluate the effect that a change in specification will have on implementation or verification.

To change a design and implementation in response to a change in specification, the developers need to correctly determine what has changed in the specification. Having a clear mechanism for showing what requirements have been removed, added, or changed, and for showing specifically how other parts of the specification have changed, makes this task possible. In particular, being able to accurately enumerate every change is important; the developer should not have to hunt for subtle changes that may be hidden.

The decisions that are encoded in a component’s design include how different parts of the component interact with and depend on each other. When a component’s design is to be changed in response to a change in specification, some parts of the design will be directly affected. For example, a decision to add a new input message to a component directly implies that new message reception and handling functions must be implemented. However, one change can affect other parts of the existing design, and the designer and implementer must find and address all of these effects. The example new input message, for example, might require changes to a database schema for storing additional information, or might affect response time behaviors that require changes to foundational concurrency control capabilities in the design. Having a clear record of how parts within one component are designed to depend on or affect each other reduces the effort involved in making this kind of change, and reduces the chances of an error stemming from some dependency being overlooked.

36.7.4 Verifying a component

The specification defines what a component should be or do; the design and implementation define how it is or does these things. Verification is the process of ensuring that the implementation produces behaviors that match the specification.

Every element of the specification should have a corresponding method for verifying compliance of the implementation. Different aspects of the specification will require different methods: some aspects can be verified by testing, such as showing that given some input A, the component responds with behavior B. Other aspects will require demonstration, such as showing that a physically representative user can see and reach control devices. Some aspects—especially safety and security—can only be verified by analysis or formal methods, such as showing that a component never enters performs some action identified as unsafe.

Verification methods involve design and implementation, similar to the design and implementation of the component itself.

Designing a verification method involves, first, determining how a specification property can be verified. (Sometimes a property is best verified using more than one approach in parallel.) once the approach—testing, review, demonstration, or analysis—has been determined, the next step is to design how that specific specification property will be checked. That can involve designing a set of test cases that cover the expected behaviors, or defining a test procedure to evaluate a mechanical component, or defining who will perform a review and what they will look for.

Implementing a verification method turns the design into a specific set of tools and actions that, when used, give a yes-or-no answer to whether the component is compliant.

The verification methods can have errors. Indeed, in some cases the verification of a property can be more complex than the component implementation it is checking. This means that the verification designs and implementation need careful scrutiny to ensure that they are, in fact, checking the specified properties and not something else.

The verification methods also must be complete: if some property is worth specifying, it is worth verifying. The verification designs and implementations need to be checked to ensure that they cover all of the specification. Explicitly recording which parts of the specification any particular verification method checks helps the task of checking completeness.

Finally, it is common for project management to track what portion of a component’s specification has been completed and verified. This can be organized by identifying each property in the specification, and tracking which verification methods check each one. As verifications are done, the project managers can determine which parts of the specification correspond to verification activities that passed.

36.8 Specification artifacts

Specification activities take as input purpose (Chapter 33) and concept (Chapter 34) artifacts that were generated during earlier work phases.

The specifications themselves involve:

The component breakdown structure ! Unknown link ref, which organizes the components that make up the system and define the entities that will have specifications written for them
For each component, some kind of index or table of contents that organize all the elements of the specification for that component
Tables of requirements ! Unknown link ref, interface definitions ! Unknown link ref, and models ! Unknown link ref that make up the specification

The elements in the specification should include traces that show how each individual part of the specification derives from some part of the objectives or concept, and conversely how each part of the objectives is reflected in the specification.

The specification artifacts should be maintained under configuration management. That means that there should be a common repository that everyone working on the system can use to retrieve (and potentially update) the artifacts. The repository should maintain separate versions of each artifact, and clearly identify which version is the current, baselined version that people should use, which versions are outdated, and which are works in progress.

The configuration management system should support people reviewing a specification, and must support recording when a particular version has been approved to be baselined.