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.

By: Kristen Eberlein 27 May 2015

Let's be careful that we use the terms "short name" and "abbreviated name" consistently throughout the spec.

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.