DITA Format

The DITA format exports Mauro models as DITA 1.3 XML documentation topics and maps, suitable for technical documentation and publishing workflows.

Overview

The DITA format (identifier: dita) transforms Mauro Data Mapper models into DITA 1.3 XML documentation. It produces:

  • Concept topics for data classes
  • Reference topics for data elements
  • DITAMAP files for navigation structure
  • Relationship tables for cross-references
  • Key definitions for reusable content

Format Identifier

Format: dita

File Extensions: .dita (topics), .ditamap (maps)

Direction Support

Direction Supported Version
Import No N/A
Export Yes 1.2.0

Multi-File Output

The DITA exporter is a multi-file exporter that creates:

  • One topic file per data class
  • One reference topic per data element (optionally)
  • Multiple DITAMAP files for different navigation views
  • Key reference maps for content reuse

Output can be packaged as a directory structure or ZIP archive.

Parameters

Parameter Type Default Description
dita.generateMaps Boolean true Generate DITAMAP files for navigation
dita.topicsDir String topics Subdirectory for class topics
dita.elementsDir String elements Subdirectory for element reference topics
dita.generateKeydefs Boolean true Generate key definition maps for content reuse
dita.includeMetadata Boolean true Include model metadata in topic frontmatter
dita.generateRelTables Boolean false Generate relationship tables for associations

Output Structure

A typical DITA export creates the following structure:

output/
├── model.ditamap              (main navigation map)
├── topics/                    (data class concept topics)
│   ├── Patient.dita
│   ├── Observation.dita
│   └── ...
├── elements/                  (data element reference topics)
│   ├── Patient-id.dita
│   ├── Patient-name.dita
│   └── ...
└── keydefs.ditamap           (key definitions)

Examples

The following examples illustrate the use of the DITA format

Export to DITA Directory

MauroImportExport.Cli export dita model.json documentation --overwrite

Export to DITA ZIP with Custom Directories

MauroImportExport.Cli export dita model.json docs.zip \
    --param dita.topicsDir=concepts \
    --param dita.elementsDir=references \
    --zip \
    --overwrite

Minimal DITA Export

MauroImportExport.Cli export dita model.json output \
    --param dita.generateKeydefs=false \
    --param dita.generateRelTables=false

DITA Topic Types

Concept Topics
Used for data classes, providing overview and context
Reference Topics
Used for data elements, providing detailed specifications
Maps
Organise topics into navigable hierarchies

Publishing

DITA output can be processed using standard DITA toolchains:

  • DITA Open Toolkit (DITA-OT) for HTML, PDF, and other formats
  • oXygen XML Editor for authoring and publishing
  • Adobe FrameMaker for professional documentation
  • Custom XSLT transformations

Best Practices

  • Use meaningful subdirectory names that reflect your documentation structure
  • Enable key definitions for content reuse across documentation sets
  • Include metadata for better document management
  • Use ZIP packaging for easy distribution to documentation teams
  • Validate DITA output using DITA-OT or oXygen validator