Requirements, Recommendations, and Permissions are encoded using AsciiDoc markup for example blocks, prepended with an role attribute containing the type of the block (i.e., its obligation)—one of “requirement”, “recommendation”, or “permission”. For example:
[.permission] ==== I recommend this ====
(Below, "requirement" is used to refer to any of these three block types.)
In addition to block type described above, following attributes are supported (see usage example below):
Indicates the subject of the requirement. Does not get rendered in final output (although this may be overridden in flavours). Multiple instances of
subjectcan be given, semicolon-delimited [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.4]
Indicates conventional label assigned to the requirement. If present, it will be rendered in final output.
May be used to give an arbitrary number of key-value pairs of tags describing the requirement. 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.
Can contain one or more of "requirement", "permission", "recommendation", comma-delimited. Using this attribute will override the obligation of the requirement.
May be used to reference the label of a requirement or definition that is imported or presupposed by this requirement. Can contain multiple semicolon-delimited labels. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.14].
Multiple instances of
inheritcan also be expressed with the
inheritmacro, which can contain markup including cross-references [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.21].
The specific data model followed by the requirement.
The applicable subclass of requirement.
[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 ====
As can be seen, the foregoing syntax can get quite awkward. For that reason, Metanorma also supports
using a definition list, marked with role attribute
[.metadata], within the requirement,
to enter the attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.4],
All attributes have the same syntax as above. That also allows
subjects as well as
be marked up as cross-references, and it allows multiple instances of an attribute to be marked up
separately. So the foregoing example can also be marked up as:
[requirement] ==== [%metadata] 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 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 I recommend this ====
Requirements can be nested (as is the case with any delimited block AsciiDoc), by adding one more delimiter symbol than its containing block; that means that nested requirements are marked up as nested examples.
[.permission] ==== I permit this ===== Example 2 ===== [.permission] ===== I also permit this ===== ====
Named blocks and descriptions
You can mark up the internal structure of a requirement to make it machine-readable, although this is not expected to be reflected in rendering.
The internal structure of requirements is marked up with open blocks, which are marked up with a succession of two or more hyphens, rather than equals signs. Each open block needs to be named with the kind of component it contains as a role attribute; the recognised values for Metanorma are:
specification (a formal statement, which may be considered the object of the requirement)
measurement-target (for quantitative requirements)
verification (verification steps for the requirement)
import (code stubs)
component (generic component of requirement) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.4]
[.requirement] ==== [.specification] -- This is a formal specification -- [.measurement-target] -- This is a measurement target -- [.verification] -- This is a verification step -- [.import] -- This is a code stub -- ====
The component value is associated with an additional
class attribute, to
specify the particular kind of component; if no such attribute is given,
the default value is "component".
[.requirement] ==== [.component,class=conditions] -- The following conditions need to be fulfilled... -- ====
The combination of example markup and open block markup allows us to combine nested requirements with internal structure for the nested requirements:
[.requirement,label="requirement A"] ==== [.requirement,label="requirement A1"] ===== [.specification] -- This is a formal specification -- ===== [.requirement,label="requirement A2"] ===== [.measurement-target] -- This is a measurement target -- ===== ====
Any text not wrapped in a named open block is considered to be part of a description.
Any text in a named open block allowed under Metanorma is considered to be a separate
subpart of the requirement. These blocks can have types, referring to the conventions
or computer frameworks that they follow. They are given by setting the
on the open block:
[.requirement,label="requirement A"] ==== This is some descriptive text. [.specification,type=EBNF] -- This is a formal specification in EBNF -- This is some more descriptive text. ====
Text in a named open block may be include or consist of machine-readable code; any such
code needs to be wrapped in turn in a source code element, which is expected to
contain an attribute giving the computer language the block is expressed in.
(The notion of "language" may be expanded to include a particular computer framework
that the code is to be run under.)
[sourcecode,text] is taken as meaning that the block is still human readable.
The language of a source code block is likely to be distinct from the type of named block
it is contained in.
[.requirement,label="requirement A"] ==== This is some descriptive text. [.verification,type=heuristic] -- [source,ruby] ---- instances.each do |i| warn "uh-oh" if i > 5 end ---- -- ====
By default, both named blocks and descriptions will be included in final output.
Often, though not always, named blocks contain machine-readable code which is not
intended to be included in the output, but is supplemental to the human-readable
description. That is signalled through the options attribute
exclude on the named block.
[.recommendation,label="/ogc/recommendation/wfs/2",subject="user"] ==== I recommend _this_. [.specification,type="tabular"] -- This is the object of the recommendation: |=== |Object |Value |Mission | Accomplished |=== -- As for the measurement targets, [.measurement-target] -- The measurement target shall be measured as: [stem] ++++ r/1 = 0 ++++ -- [.verification,type="comprehensive"] -- The following code will be run for verification: [source,CoreRoot] ---- CoreRoot(success): HttpResponse if (success) recommendation(label: success-response) end ---- -- [.import%exclude] -- [source,CoreRoot] ---- success-response() ---- -- ====