FHIR to SDC4 Holistic Mapping Strategy

About This Document: This describes the open SDC4 specification maintained by the Semantic Data Charter. SDCStudio by Axius SDC, Inc. is one commercial implementation of this specification. See ABOUT_SDC4_AND_SDCSTUDIO.md for the distinction between open specifications and commercial tools.

Executive Summary

This document provides a top-down, holistic analysis of how complete FHIR resources map to SDC4 Data Model architecture, moving beyond individual datatype mapping to show how FHIR's compositional patterns naturally align with SDC4's hierarchical structure.

Previous Analysis Gap: The prior datatype analysis (FHIR_DATATYPES_ANALYSIS.md) focused on individual primitive and complex types in isolation, using a bottom-up approach.

This Analysis: Shows how complete FHIR resources compose into SDC4 DM structures, revealing that:

• SDC4 already has most patterns FHIR needs (ReferenceRange, Audit, Participation, etc.)
• The DM → Cluster → Component hierarchy mirrors FHIR's resource structure
• Content-compliant mappings preserve semantic meaning without duplication
• Cluster reuse eliminates the need for many FHIR-specific types

1. SDC4 Architecture Overview

1.1 The DM (Data Model) Root Structure

The SDC4 specification requires a DM (Data Model) as the root of all data models.

Implementation Example (SDCStudio):

The following shows how SDCStudio (a commercial Django application by Axius SDC, Inc.) implements the DM concept:

class DM(models.Model):
    """This is the root node of a Data Model."""

    # Core Identity
    ct_id = CharField(max_length=30, unique=True)  # CUID2 identifier
    title = CharField(max_length=255, unique=True)
    description = TextField

    # Metadata (Dublin Core)
    dc_subject = CharField  # Keywords (MeSH terms)
    source = CharField      # Supporting source/URL
    rights = CharField      # License statement
    publisher = CharField   # Publisher/copyright holder
    dc_language = CharField # Language (en-US, etc.)

    # Lifecycle
    created = DateTimeField
    updated = DateTimeField
    pub_date = DateTimeField
    published = BooleanField  # Generation complete?

    # Authorship
    creator = ForeignKey(Modeler)
    edited_by = ForeignKey(Modeler)
    author = ForeignKey(Modeler)
    contrib = ManyToManyField(Modeler)  # Contributors

    # Structure - THE KEY TO EVERYTHING
    data = ForeignKey(Cluster)  # Root Cluster (the model content!)

    # Context & Provenance
    subject = ForeignKey(Party)         # Who the data is about
    provider = ForeignKey(Party)        # Who provided the data
    participations = ManyToManyField(Participation)  # Other participants

    # Audit & Attestation
    audit = ManyToManyField(Audit)
    attestation = ForeignKey(Attestation)

    # Protocol & Workflow
    protocol = ForeignKey(XdString)  # Clinical guideline, protocol ID
    workflow = ForeignKey(XdLink)    # Workflow engine reference
    acs = ForeignKey(XdLink)         # Access control system

    # Semantic Links
    pred_obj = ManyToManyField(PredObj)  # RDF triples

    # Generated Artifacts
    xsd_file = FileField        # Generated XSD schema
    xml_file = FileField        # XML instance
    json_instance_file = FileField  # JSON instance data
    jsonld_file = FileField     # JSON-LD schema
    html_file = FileField       # Documentation

    # References
    links = ManyToManyField(XdLink)  # Ad-hoc links between models

Key Insight: The DM already has structures for:

• Audit trails (audit field) → FHIR Meta.lastUpdated, etc.
• Provenance (creator, author, contrib) → FHIR provenance
• Subject/Provider (Party) → FHIR Patient/Practitioner references
• Participations → FHIR performer, author fields
• Attestation → FHIR signatures/verification
• Semantic links (pred_obj) → FHIR coding systems
• Protocol → FHIR basedOn, instantiates

1.2 The Cluster Hierarchical Structure

class Cluster(Common):
    """
    The grouping structure of Item, which may contain further instances of Item subclasses,
    in an ordered list. This provides the root Item for potentially very complex structures.
    """

    # Nested Clusters (hierarchy!)
    clusters = ManyToManyField('Cluster')

    # All Component Types
    xdboolean = ManyToManyField(XdBoolean)
    xdlink = ManyToManyField(XdLink)
    xdstring = ManyToManyField(XdString)
    xdtoken = ManyToManyField(XdToken)
    xdfile = ManyToManyField(XdFile)
    xdordinal = ManyToManyField(XdOrdinal)
    xdcount = ManyToManyField(XdCount)
    xddouble = ManyToManyField(XdDouble)
    xdquantity = ManyToManyField(XdQuantity)
    xdfloat = ManyToManyField(XdFloat)
    xdtemporal = ManyToManyField(XdTemporal)

    # List Types
    xdbooleanlist = ManyToManyField(XdBooleanList)
    xdstringlist = ManyToManyField(XdStringList)
    xddecimallist = ManyToManyField(XdDecimalList)
    # ... etc.

Inheritance from Common:

class Common(models.Model):
    """Abstract base model providing fields common to all entries except DM."""

    project = ForeignKey(Project)
    public = BooleanField  # Reusable component?
    label = CharField      # Human-readable label
    ct_id = CharField      # CUID2 identifier
    created = DateTimeField
    updated = DateTimeField
    published = BooleanField
    description = TextField

    # Semantic Links - CRITICAL!
    pred_obj = ManyToManyField(PredObj)  # RDF triples for semantics

    # Generated Code
    schema_code = TextField  # XSD generation
    app_code = TextField     # UI generation

    # Metadata
    lang = CharField
    creator = ForeignKey(Modeler)
    edited_by = ForeignKey(Modeler)
    seq = CharField  # UI sequence/tab index
    validate = BooleanField  # Hard vs soft validation

Key Insight: Every Cluster and Component has:

• Semantic links (pred_obj) → Can map FHIR terminology bindings!
• Description → Maps to FHIR definitions
• Public/reusable flag → Perfect for @FHIR library components
• Hierarchical nesting → Natural for FHIR's compositional structure

1.3 Reference Ranges - Already Built In!

class XdOrdered(XdAny):
    """Abstract class defining the concept of ordered values."""

    # FHIR needs this! And it already exists!
    reference_ranges = ManyToManyField('ReferenceRange')
    normal_status = CharField
    simple_rr = ForeignKey('SimpleReferenceRange')

class ReferenceRange(XdAny):
    """Defines a named range to be associated with any ORDERED datum."""

    definition = CharField  # "normal", "critical", "therapeutic"
    interval = ForeignKey(XdInterval)  # The actual range
    is_normal = BooleanField

class XdInterval(XdAny):
    """Generic class defining an interval (range) of a comparable type."""

    lower = CharField
    upper = CharField
    interval_type = CharField  # int, decimal, date, time, duration...
    lower_included = BooleanField
    upper_included = BooleanField
    lower_bounded = BooleanField
    upper_bounded = BooleanField
    units_name = CharField
    units_uri = URLField

CRITICAL INSIGHT: FHIR Observation.referenceRange maps directly to existing SDC4 ReferenceRange!

No need to create @FHIR:ReferenceRange - just use the native SDC4 pattern!

1.4 Party, Participation, Audit, Attestation

class Party(Common):
    """A proxy description of a party (person, organization, etc.)."""

    details = ForeignKey('Cluster')  # Cluster for party details!
    external_ref = ManyToManyField(XdLink)  # Links to external systems

class Participation(Common):
    """Model of a participation of a Party in an activity."""

    performer = ForeignKey(Party)
    function = ForeignKey(XdString)  # Role in activity
    mode = ForeignKey(XdString)  # How they participated (in-person, phone, etc.)

class Audit(Common):
    """Mechanism to identify who/where/when tracking of instances."""

    system_id = ForeignKey(XdString)
    system_user = ForeignKey(Party)
    location = ForeignKey('Cluster')

class Attestation(Common):
    """Record an attestation by a party of item(s) of record content."""

    view = ForeignKey(XdFile)  # Attested view
    proof = ForeignKey(XdFile)  # Signature/proof
    reason = ForeignKey(XdString)
    committer = ForeignKey(Party)

Key Insight: SDC4 already has:

• Party → FHIR Patient, Practitioner, Organization references
• Participation → FHIR performer, author, participant roles
• Audit → FHIR Meta (lastUpdated, versionId, source)
• Attestation → FHIR Signature, Provenance

We should map FHIR concepts to THESE, not create duplicates!

2. FHIR Resource Compositional Patterns

2.1 FHIR Patient Resource - Complete Structure

Patient Resource (DomainResource)
├── Resource Metadata
│   ├── id: string
│   ├── meta: Meta
│   │   ├── versionId: id
│   │   ├── lastUpdated: instant
│   │   ├── source: uri
│   │   ├── profile: canonical[]
│   │   ├── security: Coding[]
│   │   └── tag: Coding[]
│   ├── implicitRules: uri
│   └── language: code
│
├── Narrative
│   ├── text: Narrative
│       ├── status: code (generated|extensions|additional|empty)
│       └── div: xhtml
│
├── Identifiers (Business IDs)
│   └── identifier: Identifier[] (0..*)
│       ├── use: code (usual|official|temp|secondary)
│       ├── type: CodeableConcept
│       ├── system: uri (namespace)
│       ├── value: string (the actual ID)
│       ├── period: Period
│       └── assigner: Reference(Organization)
│
├── Demographics
│   ├── active: boolean (0..1)
│   ├── name: HumanName[] (0..*)
│   │   ├── use: code
│   │   ├── text: string
│   │   ├── family: string
│   │   ├── given: string[]
│   │   ├── prefix: string[]
│   │   ├── suffix: string[]
│   │   └── period: Period
│   │
│   ├── telecom: ContactPoint[] (0..*)
│   │   ├── system: code (phone|fax|email|pager|url|sms|other)
│   │   ├── value: string
│   │   ├── use: code (home|work|temp|old|mobile)
│   │   ├── rank: positiveInt
│   │   └── period: Period
│   │
│   ├── gender: code (male|female|other|unknown)
│   ├── birthDate: date
│   ├── deceased[x]: boolean | dateTime
│   │
│   └── address: Address[] (0..*)
│       ├── use: code
│       ├── type: code
│       ├── text: string
│       ├── line: string[]
│       ├── city: string
│       ├── district: string
│       ├── state: string
│       ├── postalCode: string
│       ├── country: string
│       └── period: Period
│
├── Relationships
│   ├── maritalStatus: CodeableConcept
│   ├── multipleBirth[x]: boolean | integer
│   │
│   ├── contact: BackboneElement[] (0..*)
│   │   ├── relationship: CodeableConcept[]
│   │   ├── name: HumanName
│   │   ├── telecom: ContactPoint[]
│   │   ├── address: Address
│   │   ├── gender: code
│   │   ├── organization: Reference(Organization)
│   │   └── period: Period
│   │
│   └── communication: BackboneElement[] (0..*)
│       ├── language: CodeableConcept (required binding to BCP-47)
│       └── preferred: boolean
│
├── Photo & Documents
│   └── photo: Attachment[] (0..*)
│       ├── contentType: code
│       ├── language: code
│       ├── data: base64Binary
│       ├── url: url
│       ├── size: integer64
│       ├── hash: base64Binary
│       ├── title: string
│       ├── creation: dateTime
│       ├── height: positiveInt
│       └── width: positiveInt
│
└── Provider References
    ├── generalPractitioner: Reference(Organization|Practitioner|PractitionerRole)[]
    ├── managingOrganization: Reference(Organization)
    └── link: BackboneElement[] (0..*)
        ├── other: Reference(Patient|RelatedPerson)
        └── type: code (replaced-by|replaces|refer|seealso)

Compositional Insights:

1. Repeating Complex Types: identifier[], name[], telecom[], address[], contact[], communication[]
2. Nested BackboneElements: contact, communication, link
3. Choice Types: deceased[x], multipleBirth[x]
4. Reference Links: generalPractitioner, managingOrganization
5. Metadata Layer: Meta, Narrative (every resource has these)

2.2 FHIR Observation Resource - Complete Structure

Observation Resource (DomainResource)
├── Resource Metadata
│   ├── id, meta, implicitRules, language (same as Patient)
│   └── text: Narrative
│
├── Identifiers & Workflow
│   ├── identifier: Identifier[]
│   ├── instantiates[x]: canonical | Reference(ObservationDefinition)
│   ├── basedOn: Reference(CarePlan|DeviceRequest|ImmunizationRecommendation...)[]
│   ├── triggeredBy: BackboneElement[] (0..*)
│   │   ├── observation: Reference(Observation)
│   │   ├── type: code (reflex|repeat|re-run)
│   │   └── reason: string
│   ├── partOf: Reference(MedicationAdministration|MedicationDispense...)[]
│   └── status: code (registered|preliminary|final|amended...) [REQUIRED]
│
├── Classification
│   ├── category: CodeableConcept[]
│   │   └── (e.g., vital-signs, laboratory, imaging, survey, etc.)
│   └── code: CodeableConcept [REQUIRED]
│       └── (WHAT was observed - LOINC, SNOMED CT)
│
├── Context
│   ├── subject: Reference(Patient|Group|Device|Location...)
│   ├── focus: Reference(Any)[]
│   ├── encounter: Reference(Encounter)
│   ├── effective[x]: dateTime | Period | Timing | instant
│   ├── issued: instant
│   └── performer: Reference(Practitioner|PractitionerRole|Organization...)[]
│
├── Value (The Actual Observation Result)
│   ├── value[x]: [CHOICE TYPE - Pick ONE]
│   │   ├── Quantity (most common - measurements)
│   │   ├── CodeableConcept (coded results)
│   │   ├── string (text results)
│   │   ├── boolean (yes/no results)
│   │   ├── integer (count results)
│   │   ├── Range (low-high range)
│   │   ├── Ratio (numerator/denominator)
│   │   ├── SampledData (waveforms)
│   │   ├── time, dateTime, Period (temporal results)
│   │   ├── Attachment (images, PDFs)
│   │   └── Reference(MolecularSequence)
│   │
│   └── dataAbsentReason: CodeableConcept
│       └── (present ONLY if value[x] absent)
│
├── Interpretation & Context
│   ├── interpretation: CodeableConcept[] (high|low|normal|critical...)
│   ├── note: Annotation[]
│   ├── bodySite: CodeableConcept
│   ├── bodyStructure: Reference(BodyStructure)
│   ├── method: CodeableConcept
│   ├── specimen: Reference(Specimen)
│   └── device: Reference(Device|DeviceMetric)
│
├── Reference Ranges (CRITICAL PATTERN!)
│   └── referenceRange: BackboneElement[] (0..*)
│       ├── low: SimpleQuantity
│       ├── high: SimpleQuantity
│       ├── normalValue: CodeableConcept
│       ├── type: CodeableConcept
│       ├── appliesTo: CodeableConcept[]
│       ├── age: Range
│       └── text: markdown
│       └── [Constraint: Must have low, high, normalValue, or text]
│
├── Multi-Component Results
│   └── component: BackboneElement[] (0..*)
│       ├── code: CodeableConcept [REQUIRED]
│       ├── value[x]: (same 13 types as parent)
│       ├── dataAbsentReason: CodeableConcept
│       ├── interpretation: CodeableConcept[]
│       └── referenceRange: BackboneElement[] (same as parent!)
│       └── [Example: Blood Pressure has systolic & diastolic components]
│
└── Relationships
    ├── hasMember: Reference(Observation|QuestionnaireResponse|MolecularSequence)[]
    └── derivedFrom: Reference(DocumentReference|ImagingStudy|Media...)[]

Compositional Insights:

1. ReferenceRange is a BackboneElement - nested structure with multiple fields
2. Component allows nested observations - recursive pattern
3. Value[x] choice type - 13 different possible types
4. Workflow linkage - basedOn, partOf, triggeredBy create chains
5. Identical patterns at root and component level - referenceRange repeats!

3. Complete Resource Mappings

This section demonstrates complete mappings of FHIR Patient and Observation resources to SDC4 DM structures. See the full markdown document for detailed implementation examples including MedicationRequest.

3.1 Key Mapping Principles

1. FHIR Meta → DM fields (not in data cluster)
   • Meta.versionId → DM version tracking
   • Meta.lastUpdated → DM.updated
   • Meta.source → DM.source (Dublin Core)
   • Meta.profile → DM.pred_obj (semantic links)
2. Repeating elements → Multiple rows OR Cluster arrays
3. Choice types → Union cluster with business rules
4. BackboneElements → Nested Clusters
5. References → @FHIR:Reference pattern

4. Architectural Alignment

4.1 DM Hierarchy Mirrors FHIR Resource Structure

4.2 Existing SDC4 Patterns FHIR Needs

CRITICAL INSIGHT: At least 40% of FHIR patterns already exist in SDC4!

Don't create @FHIR duplicates - map to native SDC4 where possible!

5. Reuse vs New Component Decision Matrix

5.1 Decision Framework

DECISION TREE:

Does SDC4 have a native pattern that matches FHIR semantics?
├── YES → Use Native SDC4
│   └── Examples: ReferenceRange, XdInterval, XdQuantity, Audit, pred_obj
│
└── NO → Is this a reusable FHIR complex type?
    ├── YES → Create @FHIR cluster component
    │   └── Examples: Identifier, HumanName, Address, ContactPoint
    │
    └── NO → Is this a FHIR primitive that needs constraints?
        ├── YES → Create @FHIR cluster (if needed) OR just use SDC4 primitive
        │   └── Examples: FHIR code → XdToken with enums
        │
        └── NO → Use vanilla SDC4 component
            └── Examples: boolean → XdBoolean, string → XdString

5.2 Create @FHIR Reusable Clusters

6. Implementation Strategy

6.1 Revised Tier 1 (Based on Holistic View)

Tier 1A: Native SDC4 (No Work Needed!)

These FHIR patterns already exist in SDC4:

1. ✅ ReferenceRange → Use XdQuantified.reference_ranges
2. ✅ Range/Interval → Use XdInterval
3. ✅ Quantity → Use XdQuantity + Units
4. ✅ Audit → Use DM.audit, Audit model
5. ✅ Provenance → Use DM.creator, author, contrib
6. ✅ Semantic codes → Use pred_obj

Action: Document the mapping, create examples, NO development needed!

Tier 1B: Critical @FHIR Clusters (4 weeks)

Create reusable cluster components:

1. Identifier (business IDs)
2. HumanName (person names)
3. Address (locations)
4. ContactPoint (telecom)
5. CodeableConcept (coded concepts)
6. Reference (resource links)
7. Period (time spans)

Success Criteria:

• 7 @FHIR clusters published
• All marked public=True, reusable
• Example Patient DM uses all 7
• Documentation shows native SDC4 reuse

6.2 Vocabulary Mapping Patterns

SDC4's powerful multi-vocabulary semantic linking architecture enables direct vocabulary-to-vocabulary mapping without UMLS intermediate:

Key Benefits:

• No UMLS Dependency: Direct vocabulary-to-vocabulary mapping
• Domain Expert Control: Modeler chooses which vocabularies to include
• Flexible Predicates: Use rdfs:seeAlso, skos:exactMatch, owl:sameAs, rdf:type based on relationship
• Multiple Simultaneous: LOINC + SNOMED + ICD-10 + Local + FHIR all on one component

7. Critical Insights

7.1 The "Zoom Out" View

Previous approach (bottom-up):

• Looked at individual FHIR datatypes in isolation
• Planned to create @FHIR clusters for everything
• Missed that SDC4 already has most patterns

Holistic approach (top-down):

• Sees complete FHIR resources as compositional hierarchies
• Recognizes SDC4's DM → Cluster → Component mirrors this
• Leverages native SDC4 for ~40% of FHIR needs
• Creates @FHIR only for reusable, FHIR-specific structures

7.2 Key Architectural Discoveries

1. ReferenceRange Already Exists!
   • FHIR Observation.referenceRange → SDC4 native ReferenceRange
   • XdInterval provides low/high bounds with units
   • No need for @FHIR:ReferenceRange cluster
2. DM Metadata = FHIR Resource Metadata
   • DM.created, updated → FHIR Meta.lastUpdated
   • DM.creator, author → FHIR Provenance
   • DM.audit → FHIR Meta, audit trail
   • pred_obj → FHIR profiles, security tags
3. Cluster Hierarchy = FHIR Composition
   • data → Cluster (root) = FHIR resource content
   • Nested clusters = FHIR BackboneElements
   • Cluster reuse = FHIR datatype reuse
4. Semantic Links Already Handle Terminology
   • pred_obj → PredObj → RDF triples
   • Maps to FHIR Coding.system, code, display
   • No need for "coding" sub-cluster in CodeableConcept!

7.3 Content-Compliant, Not Duplicate

Wrong Approach: Create @FHIR:ReferenceRange that duplicates XdInterval

Right Approach: Map FHIR ReferenceRange to native SDC4 ReferenceRange

Principle: If SDC4 has semantically equivalent pattern, use it.

Result:

• Less duplication
• Cleaner architecture
• Better semantic alignment
• Easier maintenance

Conclusion

This holistic analysis reveals that FHIR to SDC4 mapping is more natural than initially thought.

Key Findings:

1. ~40% of FHIR patterns already exist in SDC4
   • ReferenceRange, XdInterval, Audit, Participation, Attestation, pred_obj
   • Use native, don't duplicate!
2. DM → Cluster → Component hierarchy mirrors FHIR resources
   • DM = Resource with metadata
   • data (Cluster) = Resource content
   • Nested clusters = FHIR BackboneElements
3. Cluster reuse = FHIR datatype reuse
   • @FHIR:Identifier, HumanName, Address, etc.
   • Public, published, reusable across data models
   • Perfect architectural alignment
4. Semantic links (pred_obj) handle terminology
   • Maps to FHIR Coding without extra clusters
   • RDF triples for terminology bindings

Revised Implementation:

• Week 1-2: Document native patterns, create Tier 1 clusters
• Week 3-4: Complex clusters, complete Patient/Observation examples
• Optional: Advanced patterns as needed

Success Metrics:

• Patient DM uses 7 @FHIR clusters + native SDC4
• Observation DM uses native ReferenceRange
• Zero semantic duplication
• Clear, maintainable architecture

Final Recommendation: PROCEED with confidence - the architectural alignment is stronger than anticipated!

About This Documentation

This document describes the open SDC4 specification maintained by the Semantic Data Charter community.

Open Source:

• Specification: https://semanticdatacharter.com
• GitHub: https://github.com/SemanticDataCharter
• License: CC BY 4.0

Commercial Implementation:

• SDCStudio: https://axius-sdc.com (by Axius SDC, Inc.)

See ABOUT_SDC4_AND_SDCSTUDIO.md for details.

This document is part of the SDC4 Integration Guide series.
Author: Timothy W. Cook (Founder, Axius SDC, Inc.) w/Claude (Anthropic AI Assistant)
License: Creative Commons Attribution 4.0 International (CC BY 4.0)