FHIR CodeSystem Format

The FHIR CodeSystem format exports Mauro terminology models as HL7 FHIR CodeSystem resources in XML format, enabling integration with healthcare systems and FHIR-compliant applications.

Overview

The FHIR CodeSystem format (identifier: fhir-codesystem-xml) imports and exports terminology models using the HL7 FHIR (Fast Healthcare Interoperability Resources) CodeSystem resource structure. It supports:

  • FHIR R4 and R5 CodeSystem XML structure
  • Concept hierarchies with parent-child relationships
  • Multiple designation types (preferred, synonym, abbreviation)
  • Concept properties and metadata
  • Target representation options (data model, terminology, enumeration)
  • Bidirectional import and export operations

Format Identifier

Format: fhir-codesystem-xml

File Extension: .xml

MIME Type: application/fhir+xml

Direction Support

Direction Supported Version
Import Yes 0.3.0
Export Yes 0.3.0

Export Parameters

Parameter Type Default Description
includeDesignations Boolean true Include <designation> entries for admissible and alternative labels

Import Parameters

Parameter Type Default Description
targetRepresentation Choice dataModel Target Mauro representation: dataModel, terminology, or enumeration

FHIR CodeSystem Mapping

FHIR CodeSystem elements are mapped to Mauro as follows:

CodeSystem (root)
Maps to Mauro data model with FHIR metadata stored in model properties
concept
Maps to Mauro data class (when targetRepresentation=dataModel) or terminology concept
concept.code
Maps to data class identifier or is derived from label if not present
concept.display
Maps to data class label
concept.definition
Maps to data class description
concept.designation
Maps to metadata entries for synonyms, abbreviations, and alternative labels
concept.property
Maps to metadata entries preserving FHIR property codes and values
concept.concept (nested)
Maps to hierarchical data class structure or parent-child relationships

Target Representation Options

When importing FHIR CodeSystems, you can choose how concepts are represented in Mauro:

dataModel
Concepts map to data classes within a data model. Suitable for general-purpose terminology management and integration with other data structures.
terminology
Concepts map to terminology-specific structures with enhanced semantic relationships. Optimised for clinical terminology management.
enumeration
Concepts map to enumeration values. Suitable for value sets and code lists used in data element constraints.

Examples

The following examples illustrate the use of the FHIR CodeSystem format

Export to FHIR CodeSystem XML

MauroImportExport.Cli export fhir-codesystem-xml model.json terminology.xml

Export with Designations

MauroImportExport.Cli export fhir-codesystem-xml model.json codesystem.xml \
    --param includeDesignations=true \
    --overwrite

Import FHIR CodeSystem as Data Model

MauroImportExport.Cli import fhir-codesystem-xml codesystem.xml model.json \
    --param targetRepresentation=dataModel

Import as Terminology

MauroImportExport.Cli import fhir-codesystem-xml terminology.xml model.json \
    --param targetRepresentation=terminology \
    --store-key medical-terms

Import as Enumeration

MauroImportExport.Cli import fhir-codesystem-xml valueset.xml model.json \
    --param targetRepresentation=enumeration

FHIR CodeSystem Structure

Exported FHIR CodeSystem XML includes:

  • Metadata elements: id, url, version, name, title, status, publisher, date
  • Description: Narrative description of the terminology
  • Content type: Set to "complete" for full concept export
  • Count: Total number of concepts in the CodeSystem
  • Concepts: Hierarchical list of concept definitions with codes, displays, and definitions
  • Designations: Alternative labels with language and use codes (if enabled)
  • Properties: Additional concept properties preserved from source model

Code Generation

When exporting to FHIR CodeSystem, codes are determined by:

  1. Explicit code from metadata (key: "fhir.code" or "code") if present
  2. Slugified label (lowercase, alphanumeric with hyphens) if no explicit code
  3. Hash-based identifier if neither code nor suitable label exists

This ensures deterministic, stable, and FHIR-compliant code values.

Designation Support

When includeDesignations is enabled, the exporter includes:

  • Preferred terms (use code: "preferred")
  • Synonyms (use code: "synonym")
  • Abbreviations from metadata
  • Language tags for multilingual designations
  • Use context from FHIR designation use codes

Best Practices

  • Use targetRepresentation=terminology for clinical terminology imports
  • Enable includeDesignations for full semantic richness in exports
  • Store explicit FHIR codes in metadata with key "fhir.code" for stable exports
  • Use descriptive labels that produce meaningful slugified codes
  • Include version information in model metadata for FHIR version tracking
  • Set model organisation and author fields for proper FHIR publisher attribution
  • Use hierarchical data class structures to represent concept hierarchies

FHIR Compliance

The format complies with:

  • HL7 FHIR R4 CodeSystem resource specification
  • FHIR R5 compatibility (forward-compatible structure)
  • HL7 terminology services requirements
  • FHIR XML serialisation rules

Use Cases

The FHIR CodeSystem format is particularly useful for:

  • Publishing clinical terminologies to FHIR servers
  • Exchanging terminology content between healthcare systems
  • Integrating Mauro-managed terminologies with FHIR applications
  • Converting SNOMED CT, LOINC, or custom value sets to Mauro format
  • Supporting FHIR Terminology Service API implementations
  • Maintaining terminology version control and governance

Limitations

  • XML format only (JSON FHIR format not currently supported)
  • Focus on CodeSystem resource (ValueSet and ConceptMap not included)
  • Hierarchical relationships limited to parent-child via nested concepts
  • Some advanced FHIR features (supplements, expansions) not fully supported

Healthcare Integration

FHIR CodeSystem exports can be used with:

  • HAPI FHIR server for terminology hosting
  • Firely (Simplifier) for terminology management
  • NHS Digital terminology services
  • Electronic Health Record (EHR) systems with FHIR APIs
  • Clinical data warehouses and analytics platforms
  • HL7 FHIR validation and conformance tools