Metanorma: Aequitate Verum

Validation

All Metanorma XML documents that are generated by the Metanorma tool are validated against a formal schema for the document structure, as well as style rules around content.

Validation messages are written to:

The error log file has the following structure:

Error class

Line number (where available)

ID of element (where available)

Message

Context (by default, Metanorma XML)

Severity

There are four severity values, 0 through 3. Severity 0 causes execution to abort, and alerts about such fatal errors are also output to console. To date, these are applicable to all flavours of Metanorma, and are documented here. Severity 3 errors, by contrast, are information-only warnings. You must address severity 0 errors, to get documents to compile at all, and you should also address severity 1 errors.

Error classes include the following:

Style issues

Style

These are typically specific to the SDO, and reflect requirements on content set by the SDO editorial group. For example, ISO Content style validation lists the ISO-specific content style rules that Metanorma warns about when compiling ISO documents, derived from ISO/IEC DIR 2 and from the ISO House Style specification. These issues will not prevent compilation, and they are not always correct, but they do catch the kinds of issues that SDO editorial review is supposed to identify.

Markup issues

Anchors

Issue with identifiers of document elements, or resources (including URIs)

AsciiDoc Input

Issue with AsciiDoc markup, likely to prevent parsing of document

Bibliography

Issue with bibliographic markup

Crossreferences

Issue with cross-reference to document elements

Document Attributes

Issue with content of AsciiDoc document attributes

Images

Issue with images

Include

Issue with includes

Maths

Issue with mathematical expressions

Requirements

Issue with Metanorma requirements markup

Table

Issue with table format

Terms

Issue with terms & definitions format

Deciphering what has gone wrong with them may take more effort, but the errors they point to are more serious than the style errors, and typically need to be resolved for the document to be well-formed.

The following are fatal errors (Severity 0) identified as markup issues:

Anchors
  • Malformed URL

  • Duplicate, ambiguous anchor in file

Bibliography
Crossreferences

Issue with cross-reference to document elements

  • Invalid specification of index term (too many attributes, suggests missing quotation marks around a term containing a comma)

  • Mismatch of callouts and annotations on sourcecode snippet

Images

Issue with images

  • Image file not found

Include

Issue with includes

  • Specified include file does not exist.


    Note
    This issue also arises if the include is block-commented: Asciidoctor does not take block comments into account when it processes includes. Metanorma is more strict in enforcing the existence of included files than Asciidoctor is natively. To prevent bad includes from aborting execution, either put a :novalid: document attribute in the document, to prevent checking for fatal errors, or else comment out the include with a line comment instead of a block comment:
//include:missing-file[]

instead of

////
include:missing-file[]
////

Maths

Issue with mathematical expressions

  • Malformed MathML expression (whether entered as MathML, or after being converted from AsciiMath or Latexmath)

Requirements

Issue with Metanorma requirements markup

  • (In Modspec) requirement identifier is used more than once

Table

Issue with table format

  • Inconsistent number of rows specified (rowspan)

  • Inconsistent number of columns specified (colspan)

Terms

Issue with terms & definitions format

  • Concept markup ({{…​}}) points to something which is not a term or symbol

Style issues

Style

These are typically specific to the SDO, and reflect requirements on content set by the SDO editorial group. For example, ISO Content style validation lists the ISO-specific content style rules that Metanorma warns about when compiling ISO documents, derived from ISO/IEC DIR 2 and from the ISO House Style specification.

Conformance to Metanorma XML

Metanorma XML Syntax

Issue with validation of Metanorma Semantic XML. These errors deal with such things as restrictions on what kinds of text can appear where, pointers within the document that are orphaned, and elements that appear in the wrong sequence. The gem will usually (but not always!) generate HTML and Word output despite the presence of those errors. These errors can proliferate as the schema is quite strict, and should be investigated only when the document is visibly wrong; they are demoted to severity 2.