The DITA OASIS Technical Committee uses certain conventions for the names of XML grammar files. We suggest using these conventions as a best practice to facilitate interchange of grammar files.
Vocabulary modules that are intended for use outside of a narrowly-restricted context should have one or more associated, globally-unique names by which the modules can be referenced without regard to their local storage location. The globally-unique names can be public identifiers, URNs, or absolute URLs.
Document type shells should be given a name that distinguishes their name, owner, or purpose; for example, acme-concept.dtd. The document type shells that are provided by the DITA Technical Committee use the root element of the primary specialization as the basis for the file name.
Each vocabulary module has a short name that is used to construct entity names and other names that are used in associated declarations. Modules also can have abbreviated names that further shorten the short name, for example "sw-d" for the "software" domain, where "software" is the short name and "sw-d" is the abbreviated name.
For structural modules, the module name should be the element type name of the top-level topic or map type defined by the module, such as "concept" or "bookmap".
For element domain modules, the module name should be a name that reflects the subject domain to which the domain applies, such as "highlight" or "software". Domain module names should be sufficiently unique that they are unlikely to conflict with any other domains.
Use the following file-naming conventions for DTD-based specialization modules.
| Module type | File name (entities) | File name (elements) | Example |
|---|---|---|---|
| Structural | ModuleName.ent | ModuleName.mod | concept.ent or concept.mod |
| Element domain | DomainNameDomain.ent | DomainNameDomain.mod | highlightDomain.ent or highlightDomain.mod |
| Attribute domain | AttributeNameAttDomain.ent | Not applicable | deliveryTargetAttDomain.ent |
where:
Use the following file-naming conventions for RELAX NG-based specialization modules.
| Module type | File name | Example |
|---|---|---|
| Structural | ModuleNameMod.rng | conceptMod.rng |
| Element domain | DomainNameDomainMod.rng | highlightDomainMod.rng |
| Attribute domain | AttributeNameAttDomain.rng | deliveryTargetAttDomainMod.rng |
where:
Use the following file-naming conventions for XSD-based specialization modules.
| Module | File name | Example |
|---|---|---|
| Structural modules: Element groups | ModuleNameGrp.xsd | conceptGrp.xsd |
| Structural modules: All other declarations | ModuleNameMod.xsd | conceptMod.xsd |
| Domain modules | DomainName.xsd | highlightDomain.xsd |
| Attribute domain | AttributeNameAttDomain.xsd | deliveryTargetAttDomain.xsd |
where:
Use the following file-naming conventions for constraint modules.
Structural constraint modules should be named using the following format:
| DTD | qualifierTagnameConstraint.mod |
|---|---|
| RELAX NG | qualifierTagnameConstraintMod.rng |
| XSD | qualifierTagnameConstraintMod.xsd |
where:
For example, the file names for the constraint that is applied to the general task to create the strict task are strictTaskbodyConstraint.mod, strictTaskbodyConstraintMod.rng, or strictTaskbodyConstraintMod.xsd.
Domain constraint modules should be named using the following format:
| DTD | qualifierdomainDomainConstraint.ent |
|---|---|
| RELAX NG | qualifierdomainDomainConstraintMod.rng |
| XSD | qualifierdomainDomainConstraintMod.xsd |
where:
For example, the file name for a constraint module that removes the syntax diagram from the programming domain might be noSyntaxDiagramProgrammingDomainConstraint.ent.
Because of restrictions on the redefine feature of XML Schema, it is sometimes necessary to use an intermediate level of redefinition, which requires a separate XSD document. In that case, the intermediate XSD document should be named qualifierdomainDomainConstraintsInt.xsd.