Definition

Email this page to a friend   

Requirements Patterns and Ontologies

(Alias: boilerplate, disciplined natural language, structured english)

Pattern languages are like the English language - they free you from having to sort through meaningless combinations of words to communicate with others. They don't destroy your creativity, they enable it.
             - Christopher Alexander, The Timeless Way of Building

Would you like to improve your requirements writing skills? How Patterns Can Help Using requirements patterns, many technologists have experienced immediate and spectacular improvements in their English expression. You don't need to be Shakespeare to write a good technical specification. A working knowledge of a few standard sentence patterns makes a big difference. Using patterns you can also improve your writing efficiency. Learning a pattern language will reduce the time you spend staring at a blank page until your forehead bleeds.

To apply a pattern is to leverage the experience of thousands of analysts who have come before. You are no longer alone.

A Pattern Example

A sales manager wants a system to send emails to thousands of customers.

"I want to monitor the progress of each campaign while it is under way," he says. "Mailout status messages must be displayed."

The experienced analyst intuitively knows that there is missing information here. For example: What triggers the sending of a status message? Who or what sends the message? What is in the message?

Where did this intuition come from? How did the analyst identify that something was missing by looking at what was there? In these situations good analysts, sometimes unknowingly, simply reference their mental library of requirements patterns, select a suitable candidate and perform a quick gap analysis on the attributes they need for a particular type of requirement. For example, the sales manager's statement sounds like an event driven requirement. This pattern is therefore a good candidate:

{when} <event> the <actor> {shall} <action> <object of action> <further refinement of action>

After asking more questions the analyst is then able to write this more complete requirement:

{When} <each mailout attempt is complete> the < mailer> {shall} <display> <a mailout status message> <comprising: the date and time, success or failure status and mailout percent complete>.

A knowledge of pattern languages can therefore help you find what is missing by studying what is there.

How Ontologies Improve Quality

If you've got English expression under control, you've only solved part of the specification problem. Following a pattern only cleans up your syntax and helps you find missing information. But what about the meaning of what you have written? Is it correct, complete and unambiguous in your application domain? This is where ontologies take requirements specification to a new level.

An ontology is essentially a domain-specific dictionary of "things" and their relationships. In the example above the "thing" that sends the message will always be referred to as the "mailer". The ontology will also record the fact that the mailer is capable of "sending a mailout status message". As we discover what else the mailer can do, we add new <actions> to the ontology.

With an ontology in place we can discipline the writing of requirements statements, either manually or with software tool support. With the ontology as oracle, the specifier is constrained to documenting only the facts that the ontology knows to be true. For example, we cannot, by mistake, specify that the mailer sends invoices.

In this way integrating a domain ontology with a pattern language significantly improves specification quality - usually on the first release - thus eliminating expensive rework. Building an ontology is a non-trivial enterprise, but it is worth the effort. The cost of defective requirements can be crippling, especially if they are not discovered until a system is in use. Hundred million dollar failures are common (refer Saving Obamacare).

If, by alerting you to patterns and ontologies, we help you prevent just one such disaster in your entire technical career we will have been of service.

More on Ontologies

Ontologies describe the concepts present in a domain and the relationships between them. For example, the domain of aviation includes pilots and aircraft; individual pilots are certified to fly various types of aircraft. Setting out to discover why an organisation needs a complex system, an analyst is like an actor walking onto an empty stage with a great audience looking on. The difference is, rather than acting out a prewritten script, the analyst's job is to engage with the audience and discover THEIR story; to fill this great void with the objects, concepts and processes that exist in the customer's universe of discourse. What actors and things will strut the stage? What are their properties and how will they interrelate? And to describe this in the customer's own language. The body of knowledge thus created is called an ontology.

An ontology describes the meaning of your world

The origin of ontologies. The term originated circa 500 BCE with the pre-Socratic philosopher Parmenides, who explored the fundamental nature of reality by asking the questions: What is ultimately there? What is it like? How does it interact?

Ontology examples. Fast forwarding to the present, systems engineering ontologies formally represent domain knowledge as a hierarchy of concepts using a set vocabulary to denote the types, properties and interrelationships of domain concepts. A fragment of an ontology for a humble washing machine is provided below. Many more examples can be found at Stanford University's on-line tool: Web Protégé ⁶.

Constructing Requirements Patterns

Patterns (alias: boilerplate or disciplined natural language) are standard sentence structures for expressing requirements. They use consistent syntax and integrate attributes from the domain ontology of interest. Using standard patterns authors are more likely to get-it-right-the-first-time. Reviewers (including automated analysis tools) are also better equipped to judge the goodness of a requirement statement.

Here is an example of a pattern used when required behaviour is best described in terms of system states:

{while} <system state> <actor> {shall} <action> <object of action> <further refinement of action>

Where:

<system state>, <actor>, <action>, <object of action> and <further refinement of action> are placeholders for domain-specific attributes sourced from the domain's ontology and

{while} and {shall} are fixed syntactic keywords.

If this pattern were applied in the domain of aviation, an instantiation might read:

This example illustrates how the pattern provides the structure (alias: syntax) and the ontology provides the meaning (alias: semantics). Compound statements of requirement can also be constructed by combining several patterns using string concatenation.

Creating a Pattern Language

To take full advantage of this specification strategy, organisations need to develop their own pattern language by identifying a limited set of patterns that suit their particular application domain. For example, Rolls-Royce ⁴ identified five patterns that suited requirements specification for engine management systems (refer: Easy Approach to Requirements Syntax - EARS). These patterns are reproduced below - tagged (EARS).

Sample Patterns

Here are some patterns for commonly encountered classes of requirement.

Pattern: Event-Driven (EARS)

• Initiated when and only when an event occurs or is detected
• Uses the {when} keyword

Example context: Creating invoices when goods are shipped

{When} an order is shipped and the order terms are not “Prepaid” the system {shall} create an invoice.

Pattern: Capability

• Describes a high level capability
• Uses the {shall be capable of} keywords

Example context: Uninhabited air vehicle (UAV) capabilities.

{When} all communications are lost the UAV {shall be capable of} automatically navigating to base.

Pattern: State-Driven (EARS)

• In force while the system is in a specific state
• Uses the {while} or {during} keywords

Example context: Controlling display intensity on low power

{While} in low-power mode the system {shall} reduce the intensity of the user display to a configurable minimum level.

Pattern: Pre/Post Condition

• Specifies the start conditions and the end result only
• Leaves the process of achieving the end result up to the developer
• Treats the function as a black box

Example context: Recovering disk space by deleting log files

{If} greater than 80% of disk space has been consumed, the system {shall} free up disk space, {such that} a minimum of 20% of disk space is available and at least the last 30 days of log files are available. If this condition cannot be achieved the system {shall} send an error message.

Pattern: Universal Attribute (EARS)

• States a fundamental system property
• Does not require a stimulus to execute
• Exists at all times

Example context: Controlling access to medical records

The system {shall} prevent unauthorised access to patient data.

Pattern: Optional (EARS)

• Invoked only in systems that include a particular optional feature
• Uses the {where} keyword
• Exists at all times

Example context: Diverting telephone calls.

{Where} the call divert feature is present, the system {shall} allow the user to divert all incoming calls to a specified telephone number.

Pattern: Unwanted Behaviour (EARS)

• Describes things a system must not do
• Handles unwanted behaviours including error conditions, failures, faults, disturbances and other undesired events
• Uses the {if} and {then} keywords

Example context: Preventing a traffic light from displaying dangerous signals.

Unwanted condition or event	Opposing green signals detected	Opposing green signals
Actor	The traffic signalling controller
Response	De-energise
Object of action	All traffic lights

{If} opposing green signals are detected {then} the traffic signalling controller {shall} de-energise all traffic lights.

Pattern: Complex Combination

• Concatenates multiple patterns to express a complex requirement
• Describes complex conditional events involving multiple triggers, preconditions, states and/or optional features with various constraints
• Uses a combination of the keywords: {When}, {If}/{Then}, {While} and {Where}

1. Example context: Determining where photos will be stored on a digital camera.

{While} in start up mode, {when} the software detects an external flash card, the software {shall} use the external flash card to store photos.

2. Example context: Describing the behaviour of a message switcher.

{When} a message is received, {if} Message has all UTF-8 characters and has a valid routing indicator, {then} the system {shall} switch that message {within} 10 milliseconds of receipt, {from} the message input port {to} the message output port, corresponding to the routing indicator in the message.

Determining Pattern Attributes with Ontologies

Ontologies help a group of people to develop a shared vocabulary about their domain of interest. This vocabulary can then be used to unambiguously specify system requirements in that domain. Historically, ontologies were designed to represent knowledge in the field of artificial intelligence and are expected to facilitate automated logical reasoning. For example, detecting redundancies and inconsistencies in requirements. In complex systems development ontologies are used to validate requirements on input.

For example, a washing machine ontology records the objects of interest that comprise the machine and the actions that individual objects, or the machine as a whole, can perform. The following is a fragment:

Washing Machine Ontology   Actors       System   Objects       Bowl     Water inlet valve     Agitator   Actions       Open the water inlet valve     Close the water inlet valve   Parameters       Bowl level     Bowl level setpoint   Events       Bowl level exceeds the bowl level setpoint     Pause button pushed

Benefits of Ontology Based Requirements

Applying an ontology to requirements statements significantly increases their precision and consistency. In addition, given that attributes, sourced from the ontology, are applied to named placeholders in requirements patterns (e.g. <actor>, <capability>, <event> ...), it is possible to analyse the specification with a software tool. In this way the specification ceases to be a jumble of words that can only be interpreted by a human being. For example, a software tool can generate useful reports on content. Some examples are:

• A list of actors
• Actions required for a particular actor
• A list of all system capabilities or features

Applying predefined attributes also eliminates ambiguity. Examples include: a particular event is always described with the same text; an object is always referred to by the same name.

An ontology also allows automated tools to reason about the accuracy of a requirement. For example, a tool can detect an action that has been incorrectly assigned to a particular actor. For example, an airline passenger may not engage the automatic pilot.

Application Notes

The role of patterns in requirements elicitation. When capturing system requirements, analysts usually start at the conceptual level, asking what the business wants and why; they then progress to what users must be able to do; finally they write detailed descriptions of how the system should behave as viewed by a user. By their very nature the early stages of requirements specification feature creative and therefore unstructured statements of need. Recall that Steve Jobs, the creative force behind one of the most valuable companies in the world (Apple Computer), was fond of subjective requirements, demanding that a system needed to be "wickedly cool". However as we depart the conceptual world and engage with the real-world need to provide input for the design of a concrete thing, requirement statements need to be more precise - more verifable by some cost effective testing process.

A subjective requirement

Experience has shown that ontologies can be defined at all stages of analysis and specification, even at the highest level of creative visualisation, such that when the time comes to specify the lower level requirements the semantic framework is in place - terminology and behaviours are well understood and agreed to by all parties. The various requirements patterns can then be unambiguously populated.

For more on the hierarchy of requirements view our video: Specifying Software Requirements. An elicitation process is also described in our Joint Application Design page.

Analysis: distilling truth from a fog of words. In the course of requirements elicitation analysts collect reams of text. They are typically redolent with: subjective wishes ("the system must be user friendly"), human opinions ("the generation Y attention span is no greater than 140 characters") and some basic truths ("web users must experience a response time latency of no greater than three seconds to remain engaged"). The analyst's job is to tear this great body of words down to its very essence, to refine, structure, classify, model, evaluate the feasibility of, prioritise and negotiate. The output of analysis is typically: English language requirements statements and models (e.g. object models, function flow diagrams, state transition diagrams, decision trees and tables, mathematical equations ...). And hereby lies the both the problem and the solution provided by patterns.

A common problem: technologists can't write English. Technologists, often mathematically oriented and untrained in written and verbal communication skills, are good at modelling but struggle to express themselves in plain English. This becomes a problem when complete, correct and concise descriptions of system behaviour must be written for an audience of non-technical users. Requirements expressed in rambling natural language often result in ambiguity, vagueness, subjectivity, lack of clarity, lack of coherence, lack of testability and missing information. More than 50 years experience in complex system development has clearly shown that failure to capture accurate and detailed requirements has been responsible for the majority of project failures.

The solution: use a pattern language. Many organisations have persevered with pattern languages because they've observed that, once given a good example of how to articulate certain kinds of requirements, even the most illiterate of technologists write better specifications almost immediately.

Limitations of the Method

The requirements patterns provided here generate statement level requirements only. They are not useful where large quantities of repetitive information are better expressed in tabular form such as the input/output lists of supervisory control and data acquisition (SCADA) systems.

Where complex decision-making is required, a better approach is to use decision trees or tables. In application domains such as real time embedded systems, detailed requirements are better expressed with models such as the finite state machine. Note that a finite state modeling strategy would apply to a detailed behavioural specification of our humble washing machine.

Tool Support

As demonstrated above, a pattern is instantiated by assigning textual values to the attributes. These values may be manually entered by a user or selected from suggestions sourced from a domain-specific ontology. In this way some level of automation can be introduced into specification writing. For example, this technique is used by The Reuse Company's Requirements Authoring Tool - RAT ⁵.

Further Reading

A software pattern reference. Stephen Withall's book Software Requirements Patterns ⁷ provides 37 requirements patterns.

Web Protégé. Examples of ontology development using Stanford University's on-line tool: Web Protégé are at http://webprotege.stanford.edu/#List:coll=Home. Web Protégé is a free, open source collaborative ontology development environment for the Web.

The CESAR research project, funded by the European Union AREMIS program, publishes reports on the use of boilerplates. The reports also discuss formalising the approach with ontologies.