5.4 Comply-with-Standard Requirement Pattern

5.4 Comply-with-Standard Requirement Pattern

Basic Details

Related patterns:	Accessibility
Anticipated frequency:	Rarely more than 12 requirements
Pattern classifications:	Pervasive: Maybe

Applicability

Use the comply-with-standard pattern to specify that the system must comply with a particular standard.

Discussion

A standard, for the purpose of this pattern, is any document or collection of documents that makes demands on how things in its sphere are to be done. It includes laws (tax, privacy, access by people with disabilities), government regulations, industry-specific regulations and codes of conduct, company standards, quality standards (such as ISO 9001), information standards (such as currency and country codes), and technical standards of diverse kinds (for example, file formats, communication protocols, and user interface conventions).

Comply-with-standard requirements tend to be very straightforward: you must comply with whatever-it-is. But more often than not, it isn't good enough to leave it at that, and you should write extra requirements that expound the implications. See the "Extra Requirements" section later in this pattern for more. (Note that this pattern has been named "comply-with-standard" for clarity: calling it the "standard" requirement pattern would invite misreading its purpose.)

Let's divide standards into a few categories for the purpose of saying a little about how to approach them:

1. Industry-specific legislation, regulations, and codes of practice Complying with these sorts of standard often involves a lot of work, which is justified because they usually have a major bearing on the central purpose of the system. But you might still be in for a nasty surprise when you find out just how extensive and tough they are, especially if you're new to the industry in question.

2. Legislation that applies to all companies within the jurisdiction to which it applies (Such as sales tax and financial regulations.) Usually, it's not necessary to study the laws themselves: turn to an expert in that area, such as the company accountant, lawyer, finance department, or auditors, to ask them what's needed. Often it's not necessary even to mention the laws that underlie the need to support taxes and such.

3. Company standards These are usually concerned with software quality and consistency, though they might mandate certain support functions (such as system monitoring). The line between company standards and company-mandated use of common software or common requirements can be blurred. If you have any control over these things, it's best for company standards to stick to nonfunctional matters, and to have common requirements specifications for the rest.

4. Technical standards (Such as file formats and communication protocols.) Normally, you don't need to go into detail here: if you find that building your system involves developing your own implementation of a general technical standard (when that is not central to the purpose of your system), it might be a sign that something's wrong. For example, if someone asks for the system to support a peculiar file format for which no off-the-shelf software is available, you should seriously question whether it's justified.

Complying with Multiple Versions of a Standard

If complying with a standard is bad enough, dealing with multiple versions adds all sorts of complexities. It might not just mean complying with multiple versions at the same time; it might encompass changing the version(s) over time-in particular, complying with the latest version on an ongoing basis. This is very easy to state in an innocuous-sounding requirement, but in it likely lurks a can of worms. Consider the requirement "The system shall read all versions of PDF files, including the latest." What are developers and testers to make of that? Do we retest every time a new version is released? And what do we do if something suddenly doesn't work? These sorts of questions must be answered one way or another, so everyone knows where they stand.

Factors to consider:

1. Does the standard affect the functionality of the system? If not (for example, a standard that deals with quality), moving to a different version of the standard probably involves no work beyond its new demands. (That is, switching versions is not itself a problem.)

2. Does a new version of the standard supersede an old version, or must the system support multiple versions of the standard at the same time?

3. Does the standard affect any of the system's external interfaces? If so, switching to a new version must be coordinated with whoever is at the other end of the interface. You have two choices:

   1. Support old and new versions at the same time. This means the developers must build more sophisticated software.

   2. Install a new version of the system at exactly the same time as the external system(s) switch to the new version of the standard. This is akin to a juggler taking over from another juggler while the balls are in the air: it takes precise timing and even a small mistake can create a big mess.

4. Does switching to a new version (or even from one standard to another) have to happen on a specified date? For example, this is likely to happen if a new tax regime is being introduced (or when a country introduces a new currency-such as adopting the Euro). Changes like this imply the same two choices described for the previous factor-but with the extra risk of leaving you no control over when it happens.

5. Do we actually have multiple different standards for the same thing, rather than multiple versions of the same standard? For example, if the system has to deal with the tax regulations of different states, more than just the tax rates could vary (and if we're taking about different countries, they certainly will). Situations like this can have a big bearing on the system's design (and might invite use of the extendability pattern to make it easier to introduce extra instances of a like standard), so they need to be identified early and spelled out in detail. But they can be difficult to spot. At the very least, if you think this is not a problem for a particular standard, state that as an assumption in the requirements specification so that readers can check it.

6. Does the advocate of the standard expect to verify your compliance with it? If so, what compliance demands are there, and how tough are they? (They can be so onerous as to influence the whole development approach and warrant the building of many extra system functions.) If compliance is going to be hard, make everyone aware of the implications early.

Spell out the answers to all these questions in extra requirements.

It's impossible to enumerate all situations here. This rather alarming list of factors illustrates how tricky it can be to deal with multiple versions of standards-which leads to these tips:

• Tip 1: Don't commit to more than you need to. Find as many simplifications as you can: make the requirements less onerous(as far as possible). If it suffices for your system to comply with one identified version of a standard, require that only.

• Tip 2: Don't gloss over the complications involved in handling multiple versions of standards. Any complexity you ignore in the requirements won't go away and will only be harder to deal with later on.

Content

A requirement that mandates a standard should specify:

1. The name of the standard State the name clearly, such that it cannot be confused with any other standard. To achieve this, you might need to prefix it with the name of the organization who produced the standard (which means the jurisdiction in the case of laws and government regulations).

2. The purpose of the standard If the name of the standard does not convey its purpose, include a summary of what the standard is for. Usually you can do this apparently in passing (for example, "ISO3166, the international standard for country and region codes, …"). You can't expect your readers to know what an arcane code for a standard means, especially one that is numbered, and it's rude to force readers to go find out for themselves.

3. The version of the standard with which to comply If the system must comply with more than one version, or must comply with the latest version on an ongoing basis, see the preceding "Complying with Multiple Versions of a Standard" section for the extra factors you must consider. When specifying compliance with a law or government regulation, state the year it was enacted if it has no "version." If the system will only ever need to support one particular version of the standard and never any other version, say so explicitly-to avoid anyone having to worry about the awkward multiple version questions.

4. Parts of the standard with which to comply (if relevant) If the system need only comply with some parts of the standard, identify them-but be brief. If there are more than a handful of items to identify, do so using extra requirements. If you need lots of extra requirements, consider splitting them off into a separate requirements specification. Also identify any parts for which you have or might be able to obtain a temporary dispensation from compliance.

5. Location State where a copy of the standard can be found. Cite all sources likely to be available to members of the project team: the URL (Uniform Resource Locator) of a publicly available online source, hard copies (where they are stored, or who possesses them), the location of a soft copy on disk, and so on. It is advisable not to follow the location by a period ("."), to avoid the risk of it being interpreted as part of the location.

If a suitable standard exists for a particular aspect of a system, it is generally a good idea at least to seriously consider using it before devising something in-house for the same purpose. If you're not sure whether a standard exists, go and look. There are plenty out there. (This is not quite the same as the famous saying, "The nice thing about standards is that there are so many of them to choose from.") A few good starting points are

• http://www.iso.org: ISO, the International Organization for Standardization, produces a wide range of standards related to quality (the ISO 9000 series), company organization, and management, as well as industry-specific and domain-specific standards.

• http://www.w3c.org: The World Wide Web Consortium is responsible for a wide range of standards that define key aspects of the Web and adjacent subjects, including many XML-related standards.

• http://www.ietf.org: The Internet Engineering Task Force (IETF) manages the RFC (Request For Comment) standards which cover a broad range of software-related subjects, including many pertaining to the Web.

• http://www.ieee.org: The Institute of Electrical and Electronics Engineers (IEEE) produces a very large number of technical standards, including many areas of computer technology, telecommunications and quality.

• http://www.omg.org: The Object Management Group produces standards for software analysis and design (including the UML-Unified Modeling Language-standard), security, business modeling, security, and for a few specialized areas.

• http://www.oasis-open.org: The Organization for the Advancement of Structured Information Standards (OASIS) has a range of standards related to XML and connected areas, including for business processes and security.

Template(s)

Open table as spreadsheet

Summary	Definition
Comply with «Standard name» standard	The system shall comply with [parts «Standard parts list» of] the «Standard description» standard [in order to «Standard purpose»]. «Standard version statement». Source: «Standard location».

Example(s)

All the examples that follow relate to real standards (except for a couple for a fictitious company). They are divided into the four types already discussed: industry-specific, applicable to all companies, company-specific, and technical. Examples relating to accessibility legislation can be found in the accessibility requirement pattern. The first examples are industry-specific:

Open table as spreadsheet

Summary	Definition
HIPAA privacy	The system shall protect the privacy of all protected health information in compliance with the privacy rule of the U.S. Health Insurance Portability and Accountability Act (HIPAA), 1996. Protected health information is any information about an individual that concerns their health, the provision of health care to them, or payment for health care. Source: http://www.hhs.gov/ocr/hipaa
HIPAA security	The system shall comply with the security provisions of the U.S. Health Insurance Portability and Accountability Act (HIPAA), 1996 with respect to the secure storage, use of and access to protected health information (as per the previous requirement). Source: http://www.hhs.gov/ocr/hipaa

These examples demand compliance with various laws:

Open table as spreadsheet

Summary	Definition
SOX	The system shall comply with the U.S. Sarbanes-Oxley Act, 2002 (commonly referred to as SOX) to the extent of faithfully recording, protecting from improper modification, monitoring, and providing accountability for all activities within the system that have financial consequences. The intent of this requirement is to be confident that the financial information embodied in the system accurately reflects the business transacted by it, and to provide means by which auditors can verify the correctness of this information. Source: http://frwebgate.access.gpo.gov/cgi-bin/getdoc.cgi?dbname=107_cong_bills&docid=f:h3763enr.tst.pdf
U.K. Data Protection Act	The system shall protect personal information in accordance with the U.K. Data Protection Act, 1998. Source: http://www.opsi.gov.uk/acts/acts1998/19980029.htm
Australian Privacy Act 1988	All usage of information about customers and their activities, and exchange of this information between organizations, shall be in accordance with the provisions of the Australian Federal Privacy Act, 1988. Source: http://www.austlii.edu.au/au/legis/cth/consol_act/pa1988108

Here are a couple of example requirements for company-specific standards:

Open table as spreadsheet

Summary	Definition
Company coding standards	All software shall be written in compliance with the company's coding standards for the programming language in which it is written. Whenever a new programming language is introduced, a suitable coding standard shall be adopted for it.
Company Web style guidelines	All Web pages produced by the system or written in association with it shall comply with the company's Web style guidelines.

Here are example requirements for a few technical standards:

Open table as spreadsheet

Summary	Definition
ISO 639	Spoken languages shall be identified internally in the system by codes defined in ISO 639, the international standard for natural languages. (Note that this requirement does not cover the display of language choices to users-for which it is preferable to use the names of the languages.) Source: http://www.loc.gov/standards/iso639-2/langhome.html
ISO 3166	Countries and geographic regions (subdivisions) shall be identified internally in the system by codes defined in ISO 3166, the international standard for such codes. (Note that this requirement does not cover the display of countries and their subdivisions to users. It is strongly advised that only their names be shown unless there is a good reason to do otherwise.) Source: http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html
ISO 4217	The currency of all monetary amounts shall be identified internally in the system by codes defined in ISO 4217, the international standard for currency codes. (Note that this requirement does not cover the display of currencies to users. It is strongly advised that only currency names and symbols be visible to them unless there is a good reason to display the ISO code.) Source: http://www.xe.com/iso4217.htm
X.509	Digital certificates used for user authentication shall comply with X.509, the ITU-T's standard for public key and attribute certificate frameworks. (Note that this requirement does not mandate the use of digital certificates, merely that if they are used, they must be X.509-compliant.) Source: http://www.itu.int/ITU-T/asn1/database/itu-t/x/x509/1997/
PKCS #10	Interactions between the system and Certification Authorities shall comply with PKCS #10 (RSA Laboratories' standard for the syntax for certification requests sent to a Certification Authority). It is recognized that PKCS #10 defines message syntax in an abstract manner (ASN.1), so compliance with it is not in itself sufficient for a given calling system to be able to talk to a given Certification Authority. Source: http://www.rsasecurity.com/rsalabs/pkcs/pkcs-10

Extra Requirements

The natural reaction to reading a typical comply-with-standard requirement is bemusement: what's it mean? What are developers and testers supposed to do with it? If it's clear, the original requirement will suffice. If not, someone has to figure out the implications for the system by going through the standard in detail-and for consistency and efficiency, it makes sense to do this only once, rather than having several people independently making their own, uncoordinated interpretations. That person should be the analyst, and extra requirements should be their medium. It still makes sense for representatives of the development and/or testing teams to verify the analyst's interpretation against the standard itself, but the importance of that depends on the nature of the standard. Also, a small project might not have the resources to perform a lot of double-checking.

There are three levels of detail at which compliance with a standard can be specified by using requirements:

• A single requirement (As per this requirement pattern.) This suffices only if this requirement says all that needs to be said. For example a requirement that says "The 'Save as HTML' function shall produce output that complies with the HTML 4.0 standard, which resides at …" is sufficient. There's no need for the requirements to delve into the HTML 4.0 standard: it's clear to developers what HTML constructs are allowed, and testers can rigorously verify whether output complies.

• A set of requirements in the system's requirements specification If only a handful of requirements are needed to specify in detail how to comply with the standard, then include them directly. In this situation, you can omit the comply-with-standard requirement itself-though it's advisable to preface these requirements with an explanation of what they're for.

• A separate requirements specification If the standard's requirements are so numerous that they would cause the main specification to grow significantly, or they'd dominate it, create a separate requirements specification for them. Make this separate specification as general as possible: aim to specify what any system must do to comply with the standard-with a view to reuse. This isn't always possible, though, because you might write the requirements to suit the particulars of your system. So make clear whether the separate specification is suitable for reuse or not, and, if so, in what circumstances. (In an ideal world, standards would be written to be usable as requirements specifications in the first place-but I've never seen one that is.)

If you write a separate requirements specification for the standard, the original comply-with-standard requirement must identify the separate specification (its name, version, and where it can be found), and state explicitly that all its requirements must be satisfied. The comply-with-standard requirement then takes on the role of a refer-to-requirements requirement, and you should use that pattern instead.

Usually, you need to specify requirements for everything that the system must do to comply with the standard-just as if the standard were replaced by a customer who insists on everything in the standard. There are a couple of situations where it's not necessary to go into such detail: first, if you are outsourcing development to an external organization that can be expected to properly determine the implications of the standard for themselves; and second, if you intend to purchase a product. But beware of suppliers that comply with the letter of the standard but not its spirit. If you're worried about this, add requirements covering areas of potential concern.

Standard-related requirements needn't all have the same priority. For example, when a new standard is introduced, it might introduce its provisions gradually over time. (Some imposers of standards are reasonable!) Or a compliance auditor (say, for a government regulator) might grant dispensation from some demands for a given time (just like a health inspector granting a restaurant time to clean its dirty kitchen).

Some requirements that have been requested already might contribute to compliance with a standard. Add a note to this effect to each such requirement. Every requirement that contributes to compliance with a standard should say so explicitly, unless it is obvious from its context (such as being in a section of the requirements specification devoted to that standard).

If you're supplying your requirements specification to a third party (outside your organization), they must have access to all the standards you expect them to comply with. This means you must make internal organization standards available to them, and supply industry standards if the third party is unable to obtain them because they don't belong to the requisite industry body (or to save them the expense of buying them). Wherever possible, distribute copies of standards to third parties along with the requirements specification itself: it saves everyone the time of asking for and supplying them later, and it brings to light any supply problems before you suffer any embarrassment. Also bear in mind that standards can be relatively expensive, and those available only in hard copy can take significant time to order and receive. This can cause considerable difficulties if you're asking for responses (bids) from third parties, especially if you impose a closing date (for example, for a tender). This reinforces the fact that it's always helpful to your readers to spell out in detail the implications of a standard, so they don't have to pore over it themselves. It's a much better use of time for one person to figure out the implications than for multiple readers each to do it for themselves, particularly since they know less about the author's intent. It also minimizes differences in interpretation.

Many standards appear to be intentionally mean and bloody-minded. But if we consider they're nearly all written by people who aren't directly accountable for any unreasonablenesses, ambiguities, contradictions, and omissions in them, and who don't have to pay for or carry out the work necessary to comply with them-well, perhaps we should be grateful that standards aren't worse than they are.

Considerations for Development

Developers are strongly advised to consider the factors discussed in the "Complying with Multiple Versions of a Standard" section.

Be especially careful when a standard defines an interface (for example, for a communications protocol) or some other aspect of system interoperability (for example, when one system must read files produced by another system). It's very easy for two systems built to the same standard not to be able to talk to each other: it only takes very small differences in interpretation of the standard. If possible, coordinate development as closely as possible with the other organization(s) implementing the same standard.

Considerations for Testing

Standards vary considerably, so testing depends on the nature of the standard. The key to thorough and sensible testing against a standard is to get to know it firsthand.

If requirements have been specified for all the detailed implications of the standard, the parent requirement for the standard itself need not be tested.