SVG Format

The SVG format exports Mauro models as Scalable Vector Graphics diagrams, producing high-quality visual representations with optional DITA integration.

Overview

The SVG format (identifier: svg-diagrams) exports data models as visual diagrams in Scalable Vector Graphics format. It is a multi-file exporter that produces:

  • Individual SVG files for each data class
  • Hierarchical directory structure organising diagrams
  • Optional DITA topics wrapping SVG images
  • Optional DITA maps for navigation
  • Key definition maps for content reuse

Format Identifier

Format: svg-diagrams

File Extension: .svg (images), .dita (topics), .ditamap (maps)

Direction Support

Direction Supported Version
Import No N/A
Export Yes 1.0.0

Multi-File Output

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

  • One SVG file per data class showing its structure
  • One SVG file per data element (optional)
  • DITA topic files wrapping SVG images (optional)
  • DITA map files for documentation navigation (optional)

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

Parameters

Parameter Type Default Description
svg.generateDitaMap Boolean false Generate DITA map files for navigation
svg.topicsDir String topics Subdirectory for class diagram topics
svg.elementsDir String elements Subdirectory for element diagram topics
svg.imagesDir String images Subdirectory for SVG image files
svg.width Integer 800 Default SVG width in pixels
svg.height Integer 600 Default SVG height in pixels

Output Structure

A typical SVG export with DITA integration creates:

output/
├── model.ditamap              (main navigation map - if enabled)
├── images-keyrefs.ditamap     (image key definitions - if enabled)
├── topics-keyrefs.ditamap     (topic key definitions - if enabled)
├── images/                    (SVG files)
│   ├── Patient.svg
│   ├── Observation.svg
│   └── ...
├── topics/                    (DITA wrapper topics - if enabled)
│   ├── Patient.dita
│   ├── Observation.dita
│   └── ...
└── elements/                  (element-level topics - if enabled)
    ├── Patient-id.dita
    └── ...

Export SVG Diagrams

MauroImportExport.Cli export svg-diagrams model.json diagrams --overwrite

Export with DITA Integration

MauroImportExport.Cli export svg-diagrams model.json output \
    --param svg.generateDitaMap=true \
    --param svg.topicsDir=classes \
    --param svg.imagesDir=diagrams \
    --overwrite

Export to ZIP Archive

MauroImportExport.Cli export svg-diagrams model.json diagrams.zip \
    --param svg.width=1200 \
    --param svg.height=800 \
    --zip \
    --overwrite

SVG Diagram Content

Each SVG diagram includes:

  • Class name as heading
  • Table showing data elements (name, type, multiplicity)
  • Visual styling with borders and backgrounds
  • Scalable vector graphics for high-quality rendering at any size
  • Embedded metadata for accessibility

DITA Integration

When DITA generation is enabled:

  • Each SVG is wrapped in a DITA reference topic
  • Topics include the SVG as an embedded image
  • DITAMAP files provide hierarchical navigation
  • Key reference maps enable content reuse
  • Output can be processed with DITA-OT for HTML, PDF, etc.

Best Practices

  • Use default dimensions (800x600) for web documentation
  • Increase dimensions for print documentation (1200x900 or larger)
  • Enable DITA generation for integration with existing DITA documentation
  • Use ZIP packaging for easy distribution to documentation teams
  • Customise directory names to match your documentation structure
  • SVG files can be opened directly in web browsers for preview

Use Cases

The SVG exporter is particularly useful for:

  • Generating visual data dictionaries
  • Creating printable model diagrams
  • Embedding diagrams in web documentation
  • Producing high-resolution graphics for presentations
  • Integrating model visualisations into DITA documentation workflows
  • Maintaining version-controlled diagram assets

Advantages of SVG

  • Scalable: No quality loss when resized
  • Web-native: Direct display in modern browsers
  • Accessible: Can include text alternatives and ARIA labels
  • Editable: Can be modified in vector graphics editors
  • Compact: Text-based format with good compression
  • Print-friendly: High quality for printed documentation