ModSpec recommendations, requirements, and permissions

General

This document describes methods used to encode OGC requirements adhering to the OGC Modular Specification (ModSpec).

The OGC ModSpec (OGC 08-131r3) specifies a unified encoding through a set of UML models, describing how requirements in OGC standards are to be treated and presented.

Metanorma for OGC provides a special syntax for the encoding and embedding of requirements compliant to OGC ModSpec, for the exporting of machine-readable requirements as well as ModSpec compliant rendering.

Specifically, the following models in ModSpec are supported:

  • Conformance class

  • Conformance test

  • Requirements class

  • Normative statements

    • Requirement

    • Recommendation

    • Permission (not specified in ModSpec but allowed in ISO 19105, see OGC 08-131r3, 4.20)

Note
The “Conformance suite”, “Conformance module”, “Requirements module” models are not yet supported in Metanorma OGC. Please contact OGC DocTeam if support is required.

In this document, we refer to “recommendations”, “requirements” and “permissions” collectively using the generic term “requirement”.

Note
This document supplements Requirement, recommendation, and permission blocks in general Metanorma documentation.
Note

In some instances, the naming of terms that Metanorma uses in general is used in Metanorma markup instead of the nomenclature used in the OGC Modular Specification (ModSpec):

  • Metanorma uses subject to refer to what the requirement is about, rather than the more specific language of the ModSpec, to ensure that requirements are represented consistently within Metanorma.

  • The different types of requirement expressed by Metanorma for OGC are about different things, and the more abstract types of requirement are about other requirements.

Understanding ModSpec

A basic understanding of ModSpec is crucial in order to understand how to encode ModSpec-compliant models.

In simplified terms (see OGC 08-131r3, Annex C):

  • A “Requirement class” consists of multiple “Requirements”.

    • All “Requirements” within a “Requirement class” are about the same standardization target type.

  • A “Requirement” is a condition to be satisfied by a single standardization target type.

  • A “Conformance class” consists of multiple “Conformance tests”.

    • A “Conformance class” is associated with a single corresponding “Requirements class”.

    • Each “Conformance test” within the “Conformance class” corresponds to a set of “Requirements” within the corresponding “Requirements class”.

  • A “Conformance test” checks if a set of “Requirements” is met by a single standardization target (an entity).

    • A “Conformance test” has a many-to-many relation with “Requirements”.

    • A “Conformance test” is about a single standardization target.

    • A “Conformance test” can be “concrete” or “abstract” depending on the type of conformance test suite (see OGC 08-131r3, 6.4). A concrete conformance test is typically called as a “conformance test”, while an abstract conformance test is called an “abstract test”.

  • A “Test suite” is a “is a collection of identifiable conformance classes” (see OGC 08-131r3, 6.4)

    • A “Conformance test suite” contains only “Conformance classes” of the “concrete” kind. Such conformance class can only contain “concrete” conformance tests.

    • An “Abstract test suite” contains only “Conformance classes” of the “abstract” kind. Such conformance class can only contain Abstract tests.

According to the OGC Policy Directives, OGC standards that contain requirements must have those requirements conform to OGC 08-131r3.

Encoding syntax

General

A requirement (in its generic meaning) is encoded via tagged example blocks containing other tagged example blocks and open blocks.

There are two ways to encode a ModSpec model:

  1. Via definition lists

  2. Via block attributes

The definition lists method is generally recommended for its multi-line syntax but some authors may prefer specifying attributes in the header.

Note
These two methods originate from Metanorma’s general support of the alternative syntaxes for specifying a block attribute list as a definition list.

Specifying using definition lists or block attributes

In Metanorma, the following two encoding syntaxes are considered equivalent.

  • In definition list syntax, a [%metadata] definition list within a ModSpec model provides the necessary information for the specified model.

  • In block attributes syntax, the necessary information is provided as an attribute list to the block.

Rich textual input to attributes, such as for part and component, are encoded in the block attributes syntax using the [.component] role within the ModSpec model block, as in:

[.component,class=part]
--
Part A of the requirement.
--

The following two examples demonstrate encoding of a ModSpec requirement that are encoded in Metanorma XML identically (and therefore rendered identically in output).

ModSpec requirement in definition list syntax
[requirement]
.Encoding of logical models
====
[%metadata]
type:: general
label:: ogc/spec/waterml/2.0/req/xsd-xml-rules
subject:: system
part:: Metadata models faithful to the original UML model.

Logical models encoded as XSDs should be faithful to the original UML conceptual
models.
====
ModSpec requirement in attribute list syntax
[requirement,type=general,label=ogc/spec/waterml/2.0/req/xsd-xml-rules,subject="system"]
.Encoding of logical models
====

[.component,class=part]
--
Metadata models faithful to the original UML model.
--

Logical models encoded as XSDs should be faithful to the original UML conceptual
models.
====

TODO: Can we mix syntaxes?

Base ModSpec model attributes

A ModSpec model encoding requires specifying the following attributes:

  • type (mandatory). One of:

    • general for Requirement, Recommendation or Permission

    • class for Requirements class

    • verification for Conformance test

    • conformanceclass for Conformance class

    • abstracttest for Abstract test

  • label (mandatory). Label of the model, typically a URI. This must be unique in the document (as required by ModSpec), and is also used for referencing. Plain text.

  • subject (optional). Subject that the model refers to. Plain text.

  • obligation (optional). One of:

    • requirement (default)

    • recommendation

    • permission

  • model (optional when using Metanorma OGC). Type of model. The value of ogc means using OGC ModSpec models.

Differentiated types of ModSpec models allow additional attributes.

Requirement, recommendation, permission

A Requirement (or Recommendation, Permission) is encoded by setting type to general.

It supports the following attributes in addition to base ModSpec attributes:

  • type specified as general

  • conditions (optional). Conditions on where this requirement applies. Accepts rich text.

  • part (optional). A requirement can contain multiple parts of sub-requirements. Accepts rich text.

  • inherit (optional). A requirement can inherit from one or more requirements. Accepts cross-references to other requirement models, or plain text.

  • classification (optional). Classification of this requirement.

Note
Support for conditions, part [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.2].

EXAMPLE:

OGC CityGML 3.0 sample requirement with two parts
[requirement,type="general",label="/req/relief/classes"]
====
For each UML class defined or referenced in the Relief Package:

[.component,class=part]
--
The Implementation Specification SHALL contain an element which represents the
same concept as that defined for the UML class.
--

[.component,class=part]
--
The Implementation Specification SHALL represent associations with the same
source, target, direction, roles, and multiplicities as those of the UML class.
--
====
OGC GroundWaterML 2.0 sample requirement
[requirement,type="general",id="/req/core/encoding",label="/req/core/encoding"]
====
All target implementations SHALL conform to the appropriate GroundWaterML2
Logical Model UML defined in Section 8.
====

Requirements class

A “Requirements class” is encoded using type equals to class.

A Requirements class is cross-referenced and captioned as a “{Requirement} class {N}” [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.11].

Note
Classes for Recommendations will be captioned as “Recommendations class {N}”, similarly for “Requirements class {N}” and “Permissions class {N}”.

Requirements classes allow the following attributes in addition to the base ModSpec attributes:

  • Name (mandatory). Name of the requirements class should be specified as the block caption.

  • subject (mandatory). The Target Type. Rendered as Target Type.

  • inherit (optional). Dependent requirements classes. Multiple semicolon-delimited values are allowed.

  • Embedded requirements (optional). Requirements contained in a class are marked up as nested requirements.

EXAMPLE:

Example from OGC CityGML 3.0
[requirement,type="class",label="http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-building",subject="Implementation Specification"]
====
inherit:[<<rc_core,/req/req-class-core>>]
inherit:[<<rc_construction,/req/req-class-construction>>]
====

A requirements class can contain multiple requirements, specified with embedded requirements.

The contents of these embedded requirements may be specified within the requirements class, or specified outside of the requirements class (referenced using the label).

EXAMPLE:

Example from OGC GroundWaterML 2.0
[requirement,type="class",label="http://www.opengis.net/spec/waterml/2.0/req/xsd-xml-rules[*req/core*]",obligation="requirement",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"]
.GWML2 core logical model
====

[requirement,type="general",label="/req/core/encoding"]
======
======

[requirement,type="general",label="/req/core/quantities-uom"]
======
======
====

renders as:

Requirement Class 1
GWML2 core logical model

Obligation

Requirement

Target Type

Encoding of logical models

Dependency

urn:iso:dis:iso:19156:clause:7.2.2

Dependency

urn:iso:dis:iso:19156:clause:8

Dependency

http://www.opengis.net/doc/IS/GML/3.2/clause/2.4

Dependency

O&M Abstract model, OGC 10-004r3, clause D.3.4

Dependency

http://www.opengis.net/spec/SWE/2.0/req/core/core-concepts-used

Requirement

/req/core/encoding

Requirement

/req/core/quantities-uom

Embedded requirements (such as are found within Requirements classes) will automatically insert cross-references to the non-embedded requirements with the same label [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.8]:

[requirement,type="class",label="/req/conceptual"]
.GWML2 core logical model
====

[requirement,type="general",label="/req/core/encoding"]
======
======

====

[requirement,type="general",label="/req/core/encoding"]
====
Encoding requirement
====

renders as:

Requirement Class 3: GWML2 core logical model
/req/conceptual

Requirement 1:

/req/core/encoding

Requirement 1: /req/core/encoding

Encoding requirement

Conformance class

Specified using type as conformanceclass.

A Conformance class is cross-referenced and captioned as “Conformance class {N}”, and is otherwise rendered identically to a “Requirements class” [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.4].

Conformance classes support the following attributes in addition to base ModSpec attributes:

  • subject. Associated Requirement class. May be encoded as a cross-reference or as plain text. Rendered as Requirement Class.

  • Name. Specified as the block caption.

  • inherit (optional). Dependencies of the conformance class. Accepts multiple semicolon-delimited values, which each could be a cross-reference to another conformance class or plain text.

  • Nesting (optional). Conformance tests contained in a conformance class are encoded as conformance tests within the conformance class block.

Note
Conformance classes do not have a Target Type (as specified in ModSpec). If one must be encoded, it should be encoded as a Classification key-value pair.

EXAMPLE:

[requirement,type="conformanceclass",label="http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs",subject="<<rc_crs,Requirements Class 'Coordinate Reference Systems by Reference'>>",inherit="http://www.opengis.net/doc/IS/ogcapi-features-1/1.0#ats_core",classification="Target Type:Web API"]
====
====

renders as:

Conformance Class 1

Requirements Class

Requirements Class 'Coordinate Reference Systems by Reference

Dependency

http://www.opengis.net/doc/IS/ogcapi-features-1/1.0#ats_core

Target Type

Web API

Conformance test and Abstract test

A “Conformance test” can be “concrete” or “abstract” depending on the type of conformance test suite (ModSpec, 6.4).

The OGC author should identify whether a standard requires an “Abstract test suite” or a “Conformance test suite” in order to decide the encoding of “Conformance tests” (concrete tests) versus “Abstract tests”.

Conformance tests support the following attributes and components in addition to base ModSpec attributes:

  • subject. The associated requirement. May be encoded as a cross-reference or plain text. Multiple semicolon-delimited values may be provided. Rendered as Requirement.

  • Name. Specified as the requirement’s block caption.

  • inherit (optional). Dependencies. Accepts multiple semicolon-delimited values. Each may be a cross-reference or in plain text.

  • component (optional). Components of the conformance test. Accepts rich text. [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.0]. Allows the following classes:

  • Test type of a Conformance test is encoded as a classification key-value pair.

Note
Conformance Tests are excluded from the “Table of Requirements” in Word output [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.10].

EXAMPLE:

Example of Abstract test from CityGML 3.0
[[ats_core_classes]]
[requirement,type="abstracttest",label="/ats/core/classes",subject='<<req_core_classes,/req/core/classes>>']
====
[.component,class=test-purpose]
--
To validate that the Implementation Specification correctly implements the UML Classes defined in the Conceptual Model.
--

[.component,class=test-method]
--
Manual Inspection
--

For each UML class defined or referenced in the Core Package:

[.component,class=part]
--
Validate that the Implementation Specification contains a data element which represents the same concept as that defined for the UML class.
--

[.component,class=part]
--
Validate that the data element has the same relationships with other elements as those defined for the UML class. Validate that those relationships have the same source, target, direction, roles, and multiplicities as those documented in the Conceptual Model.
--
====
Example of Abstract test from DGGS
[requirement,type="abstracttest",label="/conf/crs/crs-uri",subject="<<req_crs_crs-uri,/req/crs/crs-uri>>,<<req_crs_fc-md-crs-list_A,/req/crs/fc-md-crs-list A>>,<<req_crs_fc-md-storageCrs,/req/crs/fc-md-storageCrs>>,<<req_crs_fc-md-crs-list-global,/req/crs/fc-md-crs-list-global>>",classification="Test Type:Basic"]
====

[.component,class=test-purpose]
--
Verify that each CRS identifier is a valid value
--

[.component,class=test-method]
--
For each string value in a `crs` or `storageCrs` property in the collections and collection objects,
validate that the string conforms to the generic URI syntax as specified by
https://tools.ietf.org/html/rfc3986#section-3[RFC 3986, section 3].

. For http-URIs (starting with `http:`) validate that the string conforms to the syntax specified by RFC 7230, section 2.7.1.

. For https-URIs (starting with `https:`) validate that the string conforms to the syntax specified by RFC 7230, section 2.7.2.
--

[.component,class=reference]
--
<<ogc_07_147r2,clause=15.2.2>>
--

====

renders as:

Abstract Test 1

/conf/crs/crs-uri

Requirement

/req/crs/crs-uri, /req/crs/fc-md-crs-list A, /req/crs/fc-md-storageCrs, /req/crs/fc-md-crs-list-global

Test Purpose

Verify that each CRS identifier is a valid value

Test Method

For each string value in a crs or storageCrs property in the collections and collection objects, validate that the string conforms to the generic URI syntax as specified by RFC 3986, section 3.

+ . For http-URIs (starting with http:) validate that the string conforms to the syntax specified by RFC 7230, section 2.7.1. . For https-URIs (starting with https:) validate that the string conforms to the syntax specified by RFC 7230, section 2.7.2.

Reference

OGC-07-147r2: cl. 15.2.2

Test Type

Basic

Rendering of ModSpec models

OGC ModSpec models are generally rendered as tables.

Note
This rendering method is consistent with prior OGC practice.
  • For HTML rendering, the CSS class of the requirement table is the type attribute of the requirement.

    The following types are recognised:

    • No value for Requirements

    • verification for Conformance tests

    • abstracttest for Abstract tests

    • class for Requirements classes

    • conformanceclass for Conformance classes

    The default CSS class currently assigned for HTML rendering is recommend.

  • The heading of the table (spanning two columns) is its name (the role or style of the requirement, e.g. [.permission] or [permission]), optionally followed by its title (the caption of the requirement, e.g. .Title).

  • The title of the table (spanning two columns) is its label attribute.

  • The initial rows of the body of the table give metadata about the requirement. They include:

    • The obligation attribute of the requirement, if given: Obligation followed by the attribute value

    • The subject attribute of the requirement, if given: Subject, followed by the attribute. (In other classes of requirement, the subject attribute of the requirement is rendered differently; see below.) The subject attribute can be marked up as a cross-reference to another requirement given in the same document. If there are multiple values of the subject, they are semicolon delimited [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.4].

    • The inherit attribute of the requirement, if given: Dependency followed by the attribute value. If there are multiple values of the subject, they are semicolon delimited.

    • The component components of the requirement [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.0], which capture internal components of the requirement.

      These are divided into two categories:

      • Components with a class attribute other than part are extracted in order, with the class name normalised (title case), followed by the component contents. So a component with a class attribute of conditions will be rendered as as Conditions followed by the component contents.

      • Components with the class attribute part are extracted and presented in order: each Part is rendered as an incrementing capital letter (A, B, C and so on), followed by the component contents. Any cross-references to part components will automatically be labelled with the label of their parent requirement, followed by their ordinal letter.

    • The classification attributes of the requirement, if given: the classification tag (in capitals), followed by the classification value. The classification attribute is marked up as in the rest of Metanorma: classification="key1=value1;key2=value2…​", where value is either a single string, or a comma-delimited list of values.

  • The remaining rows of the requirement are the remaining components of the requirement, encoded as table rows instead of as a definition table (as they are by default in Metanorma).

    • Components can include descriptive text.

    • Components can include open blocks marked with role attributes. That includes the legacy Metanorma components:

      • [.specification]

      • [.measurement-target]

      • [.verification]

      • [.import]

Legacy Metanorma OGC AsciiDoc syntax

For legacy reasons, a second Metanorma OGC AsciiDoc syntax is permitted for recommendations, requirements and permissions.

In this syntax, Metanorma AsciiDoc tables are used to express the data needed for requirements:

  • Type of requirement. Specified in the first table cell, one of Recommendation, Requirement or Permission.

    • Optionally followed by a number (which is ignored in parsing; the elements are renumbered automatically in rendering.)

  • Internal label. First paragraph of the second table cell.

  • Body of requirement. Second and subsequent paragraphs of the second table cell.

[[recommendation1]]
|===
|Recommendation |/ogc/recommendation/wfs/2 +

If the API definition document uses the OpenAPI Specification 3.0,
the document SHOULD conform to the
<<rc_oas30,OpenAPI Specification 3.0 requirements class>>.
|===