5.5 Refer-to-Requirements Requirement Pattern

5.5 Refer-to-Requirements Requirement Pattern

Basic Details

Related patterns:	None
Anticipated frequency:	Up to six requirements, but usually fewer
Pattern classifications:	Pervasive: Maybe

Applicability

Use the refer-to-requirements requirement pattern to specify that some or all requirements in an external requirements specification must be satisfied as if those requirements were present in the current specification.

Discussion

A detailed requirements specification for a serious commercial system is a significant document that takes considerable effort to write and, equally importantly, to read and review. Moving certain parts into separate specifications makes it easier to deal with. Spinning off the less visible or more technical parts gives the main specification a clearer focus on the matters closer to the heart of the business, but at the risk of masking from key stakeholders the overall scale and complexity of the system. Improved clarity and manageability is one good reason for referring to external specifications. Another is that those specifications can be referred to by other systems, thus saving effort (via reuse) and increasing consistency between systems. A third reason is that a specification on a specific subject tends to be written more diligently than when it's an afterthought in another specification.

Make sure that the referenced specification is accessible to the whole audience of the current system's specification. If that's not possible, either create a version of the referenced specification that everyone can access, or copy the individual requirements into the main specification. Developers must be able to read all requirements that they are expected to satisfy.

Content

A requirement that refers to external requirements needs to contain:

• Name of the referenced specification Use the name the specification calls itself, with extra clarification if it might be confused with some other similar specification.

• Version of the referenced specification This is essential. Without it, confusion might result if there's more than one version-or if a new version is produced later. Don't commit to a moving target: we're saying the requirements in this version suit us, and satisfying them is enough. In due course, it might well be beneficial to switch to a later version of the referenced specification-indeed, we might be obligated to- but do that consciously. It might involve software changes, which mustn't slip in by the back door: deal with them the same as you'd deal with any requirement changes.

  Including the date of this version of the referenced specification is helpful, too.

• The requirements that apply Must our system adhere to the whole of the referenced specification or just some of it? If all its requirements must be satisfied, say so. If not, clearly identify which parts must be satisfied-which is best done by referring to the IDs of the requirements that apply. If you need to refer to several sets of requirements, write a separate requirement for each set. If it's more convenient, you can identify those parts of the referenced specification that don't apply-that is, that all requirements must be satisfied except for those identified.

  If only one or two requirements are referenced, you could copy them into the main specification directly; the convenience to the readers probably outweighs the drawback of duplication.

• Location of the referenced specification Where does the specification live? State where it can be found.

• Information about priority Give serious consideration to the priority of the referenced requirements; don't gloss over this subject. The referenced specification might define the priority levels that it uses in a different way than our current specification does. If not, we're lucky-and we can adopt their priorities directly. Otherwise, we need to state the priorities explicitly, either by assigning one priority to them all, saying which requirements have which priorities, or defining a translation between the priority schemes used by the two specifications.

  If this information can be expressed concisely, put it in the requirement's "priority" column; otherwise, explain it in the requirement definition and say, "various" or something suitable in the "priority" column. If a normal priority level is placed in the "priority" column, then that priority applies to all the referenced requirements-though it helps to state this explicitly in the requirement definition.

Template(s)

Open table as spreadsheet

Summary	Definition
«Domain description» requirements apply	The system shall satisfy «Requirements that apply» specified in «Specification version» of the «Specification name», which resides at «Specification location». «Priority statement».

Example(s)

Open table as spreadsheet

Summary	Definition
All common requirements apply	The system shall satisfy all the requirements defined in version 2.0 of the Common Requirements Specification, which resides at x:\Specs\Common\CommonReqtsV2.0.doc. All referenced requirements have priority 1.
Basic security requirements apply	The system shall satisfy all the basic security features requirements (SR1.1–SR1.11) specified in version 1.3 of the Security Requirements Specification, which resides at x:\Specs\Security\SecurityReqtsV1.3.doc.
Access control requirements apply	The system shall satisfy all the access control requirements (SR2.1–SR2.9) specified in version 1.3 of the Security Requirements Specification, which resides at x:\Specs\Security\AccessControlReqtsV1.3.doc.

Extra Requirements

None.

Considerations for Development

Treat each applicable requirement in the external specification as if it were present in the current specification.

Considerations for Testing

The suggestion in the "Considerations for Development" section applies to testing, too.