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.

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.

Was this helpful?