Metanorma: Aequitate Verum

Author's documentation

Requirements and provisions

Purpose

Requirements are the core content of standards that describe conditions of compliance.

The term "requirement" is considered a generic term in Metanorma that represents these statements. The generic requirement is called with different names in different organizations:

  • OGC: "requirement" (OGC 08-131r3)

  • ISO/IEC: "provision" (ISO/IEC DIR 2, 3.3.1)

  • ISO/TC 211: "normative statement" (ISO/TC 211 AHG 5 report)

Note
 While there are semantic differences between definitions of the term, the described subject as its base is used in the same manner.

Typically, requirements today are read by people. However, a machine-readable approach to requirements provide additional benefits by allowing them to be consumed by automated processes and machines:

  • allows automated tools to perform analysis and interact with requirements

  • possibility of discovery and linking related or distinct requirements

Metanorma supports encoding of machine-readable requirements.

Terms and definitions

requirement

statement describing condition of compliance

model

abstraction of information instances that share a defined set of characteristics

model scheme

set of interrelated models intended to represent an aspect of the universe of discourse

requirements model scheme

set of models intending to represent requirements

model instance

description of a concept (in a structure) fitting with characteristics that belong to a particular model

Model schemes

Given that different organizations have different names for requirements, it is not surprising that different organizations consider the constituents and semantics of a requirement different as well.

These different interpretations of a requirement are generalized in Metanorma as the "requirements model scheme". i.e. there exists different requirements model schemes that represents different types of requirements.

The two major differences between requirement model schemes are:

  • structural differences: some requirement model schemes differentiate models for permissions, requirements and recommendations;

  • semantic differences: the attributes and values assigned to different requirement instances differ. For example, OGC requires all its requirement instances to have identifiers being unique URIs.

Metanorma allows requirements to be specified in the following model schemes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.1].

Note
 For details, please refer to specific pages that describe the requirements models.

Each model scheme provides models that have different structures, validation rules, and renderings of requirements.

A single document can combine requirements from different model schemes.

Note
 Mixing requirements from different requirement model schemes in the same standard can be very confusing to users, and therefore strongly discouraged.

Specifying model schemes

For most flavors, the Metanorma MRR requirements model scheme is used by default.

For Metanorma OGC, the OGC ModSpec requirements model scheme is used by default.

If other requirements model schemes are needed, they can be explicitly specified in two ways:

  1. Document-wide specification. Use the :requirements-model: document attribute to specify the requirements model for the current document.

    If you want the requirements in an ISO document to be ModSpec, add requirements-model: ogc as a document attribute to the document.

  2. Instance specification. Use the model attribute to specify the model specific to that requirement. This is extra effort, and only makes sense if you will use more than one model within a document.

    Note
    		 The model attribute cannot be specified in a definition list, unlike other arguments.

Specification of model instances

Requirements model schemes provide a set of models that represent different types of requirements.

In order to specify a requirement, it is necessary to "instantiate" a model — fill in content into a requirements model.

In Metanorma, requirement models are specified using a block syntax similar to that of examples.

Within the requirement block, a definition list marked with [%metadata] is used to enter attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.4].

Example 1. Metanorma requirement block
[{type-of-requirement},{model-scheme}]
====
[%metadata]
{attribute}:: {attribute value}
{attribute}:: {attribute value}
...

{description}
====

Where:

  • {type-of-requirement} is the name of the requirement model within a requirements model scheme

  • {model-scheme} is the name of the model scheme. The default is Metanorma MRR for most flavors.

  • {attribute} are names of attributes

  • {attribute value} are values of the corresponding attributes

  • {description} is the description of the requirement

Certain attributes, like subject and inherit, accept complex values, such as cross-references, and it allows multiple instances of an attribute to be marked up separately.

Note
 The model scheme should not be specified in the definition list as model. The processing of the definition list varies by model, and Metanorma needs to be aware of which model to apply as early as possible.
Example 2. Example of an OGC ModSpec requirement with complex values
[requirement,model=ogc]
====
[%metadata]
type:: class
identifier:: http://www.opengis.net/spec/waterml/2.0/req/xsd-xml-rules[*req/core*]
subject:: Encoding of logical models
inherit:: urn:iso:dis:iso:19156:clause:7.2.2
inherit:: urn:iso:dis:iso:19156:clause:8
inherit:: http://www.opengis.net/doc/IS/GML/3.2/clause/2.4
inherit:: O&M Abstract model, OGC 10-004r3, clause D.3.4
inherit:: http://www.opengis.net/spec/SWE/2.0/req/core/core-concepts-used
inherit:: <<ref2>>
inherit:: <<ref3>>
classification:: priority:P0
classification:: domain:Hydrology,Groundwater
classification:: control-class:Technical
obligation:: recommendation,requirement

The XML encoding shall pass validation against the WaterML 2.0 XSD.
====

Common attributes for specifying requirement models

The following attributes are supported for requirement instances (across requirement models and requirement model schemes):

model

The requirement model scheme that applies to the instance.

type

The data model type of the instance.

identifier

The identifier assigned to an instance. Identifiers can be simple strings, and are often entered as URIs or URNs. If present, it will be rendered in final output. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.0]

Note
 identifier was previously called label.
classification

May be used to give an arbitrary number of key-value pairs of tags describing the instance. Key and value are separated by a colon, multiple values are delimited by comma, and key-value pairs are delimited by semicolon. Both key and value are expected to be tokens containing no punctuation.

obligation

The modality of the instance, as in the strength to which it pertains to compliance. Can contain one or more of requirement, permission, recommendation, comma-delimited. Using this attribute will override the obligation of the requirement.

Any attributes that are not included in the list of requirement attributes above are treated as "classification tags". [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.0]

Other attributes may be supported in different models: refer to model documentation.

Alternative attribute list specification syntax

Metanorma also allows encoding of the attribute list as options following the definition of the requirement block.

However, this syntax only works well for attributes with shorter values and can only specify values as plain text.

Note
 The length can be a concern! Attribute lists specified in this manner cannot be split into multiple lines.
Example 3. Attributes specified in an option list
[requirement,model=ogc,type="class",label="http://www.opengis.net/spec/waterml/2.0/req/xsd-xml-rules[*req/core*]",subject="Encoding of logical models",inherit="urn:iso:dis:iso:19156:clause:7.2.2;urn:iso:dis:iso:19156:clause:8;http://www.opengis.net/doc/IS/GML/3.2/clause/2.4;O&M Abstract model, OGC 10-004r3, clause D.3.4;http://www.opengis.net/spec/SWE/2.0/req/core/core-concepts-used",classification="priority:P0;domain:Hydrology,Groundwater;control-class:Technical",obligation="recommendation,requirement"]
====
inherit:[<<ref2>>]
inherit:[<<ref3>>]
I recommend this
====