File naming conventions
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.
Globally unique identifiers
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
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.
Module names
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.
DTD-based specialization modules
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:
- ModuleName is the name of the element type, such as "concept" or "glossentry".
- DomainName is the name of the domain, for example, "highlight" or "utilities".
- AttributeName is the name of the specialized attribute, for example, "deliveryTarget".
RELAX NG-based specialization modules
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:
- ModuleName is the name of the element type, such as "concept" or "glossentry".
- DomainName is the name of the domain, for example, "highlight" or "utilities".
- AttributeName is the name of the specialized attribute, for example, "deliveryTarget".
XSD-based specialization modules
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:
- ModuleName is the name of the element type, such as "concept" or "glossentry".
- DomainName is the name of the domain, for example, "highlight" or "utilities".
- AttributeName is the name of the specialized attribute, for example, "deliveryTarget".
Constraint modules
Use the following file-naming conventions for constraint modules.
- Structural modules
-
Structural constraint modules should be named using the following format:
DTD qualifierTagnameConstraint.mod RELAX NG qualifierTagnameConstraintMod.rng XSD qualifierTagnameConstraintMod.xsd where:
- qualifier is a string that is specific to the constraints module and characterizes it, for example, "strict" or "requiredTitle" or "myCompany-".
- Tagname is the element type name with an initial capital, for example, "Taskbody" or "Topic".
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 modules
-
Domain constraint modules should be named using the following format:
DTD qualifierdomainDomainConstraint.ent RELAX NG qualifierdomainDomainConstraintMod.rng XSD qualifierdomainDomainConstraintMod.xsd where:
- qualifier is a string that is specific to the constraints module and characterizes it, for example, "noSyntaxDiagram" or "myCompany-".
- domain is the name of the domain to which the constraints apply, for example, "Highlighting" or "Programming".
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.