RELAX NG: Overview of coding requirements

RELAX NG modules are self-integrating, which means that they automatically add to the content models and attribute sets they extend. This means that information architects do not have much work to do when assembling vocabulary modules and constraints into document type shells.

In addition to simplifying document-type shells, the self-integrating aspect of RELAX NG results in the following coding practices:

Each specialized vocabulary module consists of a single file, unlike the two required for DTDs.
Domain modules directly extend elements, unlike DTDs, which rely on an extra file and extensions within the document-type shell.
Constraint modules directly include the modules that they extend, which means that just by referencing a constraint module, the document-type shell gets everything it needs to both define and constrain a vocabulary module.

RELAX NG grammars for DITA document-type shells, vocabulary modules, and constraint modules MAY do the following:

Use the <a:documentation> element anywhere that foreign elements are allowed by RELAX NG. The <a:documentation> element refers to the <documentation> element type from the http://relaxng.org/ns/compatibility/annotations/1.0 as defined by the DTD compatibility specification. The prefix "a" is used by convention.
Use <div> to group pattern declarations.
Include embedded Schematron rules or any other foreign vocabulary. Processors MAY ignore any foreign vocabularies within DITA grammars that are not in the http://relaxng.org/ns/compatibility/annotations/1.0 or http://dita.oasis-open.org/architecture/2005/ namespaces.

Syntax for RELAX NG grammars

The RELAX NG specification defines two syntaxes for RELAX NG grammars: the XML syntax and the compact syntax. The two syntaxes are functionally equivalent, and either syntax can be reliably converted into the other by using, for example, the open-source Trang tool.

DITA practitioners can author DITA modules using one RELAX NG syntax, and then use tools to generate modules in the other syntax. The resulting RELAX NG modules are conforming if there is a one-to-one file correspondence. Conforming RELAX NG-based DITA modules MAY omit the annotations and foreign elements that are used in the OASIS grammar files to enable generation of other XML grammars, such as DTDs and XML Schema. When such annotations are used, conversion from one RELAX NG syntax to the other might lose the information, as processors are not required to process the annotations and information from foreign vocabularies.

The DITA coding requirements are defined for the RELAX NG XML syntax. Document type shells, vocabulary modules, and constraint modules that use the RELAX NG compact syntax can use the same organization requirements as those defined for the RELAX NG XML syntax.