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.

Tip

During build you may see a sequence of warnings—pay attention to them!

Content style rules

The content style warnings come first, and are prefixed with <flavor name> Style.

Currently, among officially supported Metanorma document flavors, content style rules are only implemented for ISO standards. There is no generic reference for content style rules; if you’re using the Metanorma to author ISO documents, see Metanorma ISO flavor docs for ISO-specific content style rules.

Syntax validation

The syntax errors come afterwards, and they report the line number and line position of the syntax error in the Metanorma XML document generated by the gem. (For example, the Asciidoctor document rice.adoc generates the Metanorma XML file rice.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. 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 need to be resolved for the document to be well-formed. The gem will usually (but not always!) generate HTML and Word output despite the presence of those errors.

For example:

value of attribute "date" is invalid; must be an ISO date @ 454:183
element "review" missing required attribute "from" @ 454:183
element "subsection" not allowed here; expected the element end-tag or element "admonition", "dl", "example", "figure", "formula", "note", "ol", "p", "quote", "review", "sourcecode", "table" or "ul" @ 467:52
value of attribute "date" is invalid; must be an ISO date @ 476:233
IDREF "Annex-A-2" without matching ID @ 315:50
IDREF "last_conformance_class" without matching ID @ 649:236
IDREF "Annex-A" without matching ID @ 308:141

The Metanorma XML schema seeks to be consistent as much as possible across flavours, but individual flavours have rules of their own, which are policed through syntax validation.

Citations

The tool also validates terms cited from the International Electrotechnical Vocabulary (IEV) against the online IEV Electropedia entries. If the preferred term does not match the form given in the IEV for that entry, it will issue a warning.