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:


During build you may see a sequence of warnings — please 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 are of two classes: warnings and errors generated in the code, and errors generated by parsing the generated Metanorma XML against the document schema. Parsing errors report the line number and line position of the syntax error; code generated errors cannot report a line number, and instead supply the nearest internal cross-reference where possible. 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.


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.