FHIR Datatypes Analysis and SDC4 Mapping Strategy

Executive Summary

This document provides a comprehensive analysis of HL7 FHIR (Fast Healthcare Interoperability Resources) R4 datatypes and their mapping to SDCStudio's SDC4 component system. Version 2.0 adds holistic top-down analysis showing how complete FHIR resources map to SDC4's existing architectural patterns, revealing that SDC4 already has ~40% of what FHIR needs natively.

Key Findings - Bottom-Up (Datatype Level)

• ✅ SDC4 types can directly map ~90% of FHIR primitives
• ✅ Cluster system is ideal for FHIR complex types
• ✅ Component reuse architecture aligns perfectly with FHIR structure
• ⚠️ Repeating elements and choice types require strategic handling
• 🎯 Tier 1 (7 critical components) enables 80% of healthcare use cases

Key Findings - Top-Down (Architecture Level) ⭐ NEW

• ✅ SDC4 native patterns match ~40% of FHIR needs (ReferenceRange, Audit, Attestation, Participation, XdInterval, pred_obj)
• ✅ DM metadata fields map directly to FHIR Meta (no duplication needed)
• ✅ DM → Cluster → Component hierarchy mirrors FHIR Resource composition
• ✅ Content-compliant mapping possible by using native SDC4 where semantically equivalent
• 🎯 Reduced component creation from initial estimate by ~30% (use native patterns)

Critical Architectural Insight

FHIR Range/ReferenceRange → Use Native SDC4 ReferenceRange! Do not create @FHIR:Range cluster. SDC4's XdQuantified.reference_ranges already implements this pattern with low/high/type/appliesTo fields.

Strategic Recommendation: PROCEED with revised phased implementation leveraging native SDC4 patterns where possible, creating @FHIR components only for unique FHIR structures (Identifier, HumanName, Address, ContactPoint, CodeableConcept, Reference).

See Also: FHIRTOSDC4HOLISTICMAPPING.md for complete top-down resource analysis and FHIRSDC4DECISION_MATRIX.md for detailed mapping decisions.

Table of Contents

Part I: Holistic Architecture View (Top-Down) ⭐ NEW

1. SDC4 Native Patterns for FHIR
2. Holistic Mapping Philosophy
3. Native vs @FHIR Decision Framework

Part II: Datatype Analysis (Bottom-Up)

1. Complete FHIR Datatypes Inventory
2. Current SDC4 Component Types
3. FHIR-to-SDC4 Mapping Strategy

Part III: Implementation Strategy

1. Implementation Priority Recommendations
2. Strategic Recommendations
3. Critical Considerations and Challenges
4. Implementation Roadmap
5. Success Metrics
6. Next Steps
7. Resource Requirements

Part I: Holistic Architecture View (Top-Down)

1. SDC4 Native Patterns for FHIR

Critical Discovery: SDC4 already implements ~40% of FHIR's structural patterns natively. Before creating @FHIR components, check if SDC4 already has the semantic equivalent.

1.1 Native SDC4 Patterns That Match FHIR

DO NOT CREATE @FHIR COMPONENTS FOR THESE - Use native SDC4 instead!

ReferenceRange (⭐ Most Important)

FHIR: Observation.referenceRange, Range datatype

SDC4: ReferenceRange and SimpleReferenceRange models + XdQuantified.reference_ranges ManyToMany

Structure:

# SDC4 ReferenceRange model (already exists!)
class ReferenceRange(XdAny):
    meaning: XdString  # "normal", "critical", etc.
    range: XdInterval  # low/high with units
    applies_to: many XdToken  # age ranges, populations

Usage in Observation:

# Blood glucose measurement
glucose = XdQuantity(
    label="Blood Glucose",
    units=ucum_mgdl,  # mg/dL
    fraction_digits=1
)

# Add reference ranges (NATIVE!)
normal_range = ReferenceRange.objects.create(
    meaning=XdString(label="Normal"),
    range=XdInterval(
        lower=70.0,
        upper=100.0,
        units=ucum_mgdl
    )
)

glucose.reference_ranges.add(normal_range)

MD2PD Template (shows native usage):

### Column: blood_glucose
**Type**: decimal
**Units**: mg/dL
**Description**: Fasting blood glucose measurement
**Constraints**:
  - precision: 1
  - range: [50, 600]

**Reference Ranges**:  ← NATIVE SDC4!
- Normal: 70-100 mg/dL (fasting)
- Pre-diabetes: 100-125 mg/dL
- Diabetes: ≥126 mg/dL

Why This Matters:

• No need to create @FHIR:Range cluster
• No need to create @FHIR:ReferenceRange cluster
• SDC4's implementation is already FHIR-compatible
• Less duplication, cleaner architecture

XdInterval

FHIR: Range (low/high bounds), Period (start/end times)

SDC4: XdInterval model

Structure:

class XdInterval(XdOrdered):
    lower: decimal/int (depends on interval_type)
    upper: decimal/int
    lower_included: bool
    upper_included: bool
    interval_type: choice (integer, decimal, temporal)
    units: FK to Units

Usage:

• FHIR Range → XdInterval(interval_type='decimal', units=...)
• FHIR Period → Two XdTemporal fields OR XdInterval(interval_type='temporal')

Example:

# Age range: 18-65 years
age_range = XdInterval(
    lower=18,
    upper=65,
    interval_type='integer',
    units=years,
    lower_included=True,
    upper_included=True
)

DM Metadata → FHIR Meta

FHIR: Resource.meta (versionId, lastUpdated, source, profile, security, tag)

SDC4: DM model fields

Direct Mapping:

Usage: Store FHIR metadata at DM level, NOT in data cluster

Audit Trail and Provenance

FHIR: Meta.lastUpdated, Provenance resource

SDC4: DM.created, DM.updated, DM.creator, DM.edited_by, Audit model

Structure:

class DM(XdAny):
    created: DateTime  # FHIR Provenance.recorded
    updated: DateTime  # FHIR Meta.lastUpdated
    creator: FK Modeler  # FHIR Provenance.agent
    edited_by: FK Modeler
    author: str  # FHIR Provenance.agent (name)
    contrib: list  # FHIR Provenance.agent (contributors)
    audit: M2M Audit  # Full audit trail

Why Use Native:

• DM already tracks lifecycle
• Audit model provides detailed change history
• No need for separate @FHIR:Provenance cluster in data

Attestation and Signature

FHIR: Signature datatype

SDC4: Attestation model, DM.attestation

Structure:

class Attestation(XdAny):
    attested_view: XdString  # What was attested
    proof: XdString  # Digital signature
    reason: XdString  # Why attested
    time_committed: XdTemporal  # When
    is_pending: bool
    committer: M2M Participation  # Who

Usage: Legal validation already modeled in SDC4

Participation and Performer Roles

FHIR: Observation.performer, Procedure.performer, performer roles

SDC4: Participation model, DM.participations

Structure:

class Participation(XdAny):
    function: XdToken  # Role (performer, author, verifier)
    performer: FK Party  # Who
    time: XdInterval  # When
    mode: XdToken  # How (in-person, remote, etc.)

Usage: Role-based attribution already in SDC4

Semantic Links and Terminology Codes

FHIR: Coding (system, code, display), CodeableConcept.coding[]

SDC4: PredObj model, pred_obj ManyToMany on all XdAny

Structure:

class PredObj(XdAny):
    pred_uri: XdLink  # Predicate (e.g., rdfs:isDefinedBy, skos:exactMatch)
    obj_uri: XdLink  # Object (e.g., LOINC code URI)
    obj_val: XdString  # Optional literal value

FHIR Coding Mapping:

# FHIR: { "system": "http://loinc.org", "code": "2339-0", "display": "Glucose" }
# SDC4:
glucose_component.pred_obj.add(
    PredObj.objects.create(
        pred_uri="http://www.w3.org/2000/01/rdf-schema#isDefinedBy",
        obj_uri="http://loinc.org/2339-0",
        obj_val="Glucose [Mass/volume] in Blood"
    )
)

Why Use Native:

• More flexible than rigid Coding cluster
• Supports multiple code systems naturally
• RDF-based (better for semantic web)
• Already integrated with XSD generation

1.2 When Native Patterns Are Sufficient

Use Native SDC4 Instead of @FHIR When:

2. Holistic Mapping Philosophy

2.1 Content-Compliant vs Structure-Duplicate

Principle: Map FHIR concepts to semantically equivalent SDC4 patterns, not structurally identical.

Example - WRONG Approach (Structure-Duplicate):

## Sub-Cluster: Range  ❌
**ReuseComponent**: @FHIR:Range
### Column: low
**Type**: decimal
### Column: high
**Type**: decimal

Example - RIGHT Approach (Content-Compliant):

### Column: systolic_bp
**Type**: decimal
**Units**: mmHg
**Description**: Systolic blood pressure
**Reference Ranges**:  ✅ Uses native SDC4!
- Normal: 90-120 mmHg
- Elevated: 120-129 mmHg
- Hypertension Stage 1: 130-139 mmHg
- Hypertension Stage 2: ≥140 mmHg

The second approach uses SDC4's native ReferenceRange pattern instead of creating a duplicate @FHIR:Range cluster.

2.2 DM Architecture Mirrors FHIR Resources

FHIR Resource Structure:

Resource
├── id, meta (metadata)
├── text (human-readable)
├── extension[] (custom fields)
└── [domain content] (actual data)

SDC4 DM Structure (perfect match!):

DM
├── ct_id, created, updated (metadata)
├── description (human-readable)
├── pred_obj[] (semantic links, like extensions)
└── data → Cluster (domain content)

Mapping:

2.3 Hierarchical Composition Patterns

FHIR Nesting:

Patient
├── identifier[] (Identifier datatypes)
├── name[] (HumanName datatypes)
├── telecom[] (ContactPoint datatypes)
└── address[] (Address datatypes)

SDC4 Nesting (clusters = reusable components):

DM: Patient Demographics
└── data: Patient Cluster
    ├── identifier_mrn → @FHIR:Identifier
    ├── identifier_ssn → @FHIR:Identifier
    ├── name_legal → @FHIR:HumanName
    ├── name_preferred → @FHIR:HumanName
    ├── phone_mobile → @FHIR:ContactPoint
    ├── email → @FHIR:ContactPoint
    └── address_home → @FHIR:Address

Key Insight: FHIR's compositional model (resource contains datatypes) perfectly matches SDC4's hierarchical model (DM → Cluster → sub-Clusters → Components).

2.4 Semantic Preservation Over Structural Mimicry

Goal: Preserve FHIR's semantic meaning, not replicate its exact structure.

Example: FHIR CodeableConcept

Structural Mimicry (❌ Too Literal):

## Sub-Cluster: CodeableConcept
  ## Sub-Cluster: Coding (repeating)
    ### Column: system
    **Type**: url
    ### Column: code
    **Type**: text
    ### Column: display
    **Type**: text
  ### Column: text
  **Type**: text

Semantic Preservation (✅ Content-Compliant):

### Column: diagnosis_code
**Type**: text
**Description**: Primary diagnosis code
**Enumeration**: [ICD-10 codes here]
**Semantic Links**:
  - http://hl7.org/fhir/sid/icd-10/E11.9 (Type 2 diabetes)
  - http://snomed.info/sct/44054006 (Type 2 diabetes mellitus)
**Examples**: E11.9, E11.65, E11.22

This uses:

• XdToken for the code field
• semanticlinks (maps to predobj) for FHIR Coding.system/code
• Human-readable text in description
• Simpler, more usable, semantically equivalent

3. Native vs @FHIR Decision Framework

3.1 Decision Tree

                    FHIR Concept
                         |
                         v
            Does SDC4 have native pattern?
                    /         \
                  YES          NO
                   |            |
                   v            v
         Use Native SDC4    Is it reusable
              (DONE!)       across resources?
                                /         \
                              YES          NO
                               |            |
                               v            v
                        Create @FHIR   Direct mapping
                         Cluster        in template

3.2 Use Native SDC4 When...

✅ Exact semantic match exists

• FHIR Range → SDC4 ReferenceRange
• FHIR Period → SDC4 XdInterval or two XdTemporal
• FHIR Coding → SDC4 pred_obj (semantic links)

✅ Metadata or lifecycle tracking

• FHIR Meta → DM created/updated/audit
• FHIR Provenance → DM creator/author/contrib
• FHIR Signature → Attestation

✅ Structural pattern already implemented

• FHIR performer roles → Participation
• FHIR contained references → (handle at data level)

3.3 Create @FHIR Cluster When...

🔧 Unique FHIR structure

• HumanName (prefix, given, family, suffix, use)
• Address (line, city, state, postal, country, use, type)
• Identifier (system, value, use, type, period)

🔧 Reusable across multiple FHIR resources

• ContactPoint (used in Patient, Practitioner, Organization, Location)
• Reference (used everywhere for links)
• CodeableConcept (used for all coded values)

🔧 Complex composition not in SDC4

• Timing (complex recurrence patterns)
• Dosage (medication instructions with nested choice types)

3.4 Direct Map (No Cluster) When...

⚡ Simple primitive type

• boolean → XdBoolean
• integer → XdCount
• decimal → XdQuantity
• string → XdString
• date → XdTemporal

⚡ Single-use complex pattern

• Resource-specific nested structures
• One-off compositions

3.5 Quick Reference Table

4. Vocabulary and Terminology Architecture

4.1 SDC4's Multi-Vocabulary Semantic Linking

Core Principle: SDC4 allows components to be semantically linked to multiple vocabularies simultaneously using RDF predicates, putting semantic definition control in the hands of the domain expert (modeler).

Architecture Overview

┌──────────────────────────────────────────────────────────────┐
│          Component Semantic Definition System                 │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Component (e.g., "Blood Glucose Observation")              │
│        ↓                                                     │
│   semantic_links (ManyToMany)                               │
│        ↓                                                     │
│   ┌────────────────────────────────────────┐                │
│   │  PredObj (Predicate-Object pairs)     │                │
│   │  ────────────────────────────────────  │                │
│   │  predicate: rdfs:seeAlso              │                │
│   │  object_uri: http://loinc.org|2339-0  │ ← LOINC       │
│   └────────────────────────────────────────┘                │
│   ┌────────────────────────────────────────┐                │
│   │  PredObj                               │                │
│   │  ────────────────────────────────────  │                │
│   │  predicate: skos:exactMatch           │                │
│   │  object_uri: http://snomed.../33747003 │ ← SNOMED CT   │
│   └────────────────────────────────────────┘                │
│   ┌────────────────────────────────────────┐                │
│   │  PredObj                               │                │
│   │  ────────────────────────────────────  │                │
│   │  predicate: rdf:type                  │                │
│   │  object_uri: http://local.../GLU-001  │ ← Local Codes │
│   └────────────────────────────────────────┘                │
│                                                              │
│  Result: ONE component → THREE vocabularies                 │
│          Direct cross-vocabulary mapping                    │
│          No UMLS intermediate needed!                       │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Key Architectural Components

1. PredObj Model (src/dmgen/models.py):

class PredObj(models.Model):
    """Represents RDF triple objects for semantic linking"""
    po_name = CharField(max_length=100)         # Human-readable name
    predicate = ForeignKey(Predicate)           # RDF predicate
    object_uri = CharField(max_length=2000)     # Target vocabulary URI
    project = ForeignKey(Project)               # Organizing project
    public = BooleanField(default=True)         # Availability

2. Predicate Model:

class Predicate(models.Model):
    """RDF predicates for semantic relationships"""
    ns_abbrev = ForeignKey(NS)         # Namespace (rdfs, skos, owl, etc.)
    class_name = CharField()           # Predicate name (seeAlso, exactMatch, etc.)

3. Namespace Model (NS):

class NS(models.Model):
    """Namespace definitions for vocabularies"""
    abbrev = CharField()               # e.g., "loinc", "snomed", "rdfs"
    uri = CharField()                  # Full namespace URI

4. Component Integration:

All XdAny subclasses (XdString, XdQuantity, XdToken, etc.) inherit:

pred_obj = models.ManyToManyField('PredObj', related_name='%(class)s_links')

RDF Predicates Supported

Modeler Flexibility: Domain expert chooses appropriate predicate based on semantic relationship.

4.2 Runtime Enumeration vs Semantic Definition

Critical Distinction: SDC4 separates runtime constraints from semantic meaning.

┌─────────────────────────────────────────────────────────────┐
│ TWO ORTHOGONAL CONCEPTS FOR COMPONENT DEFINITIONS           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ 1️⃣ RUNTIME ENUMERATION                                     │
│    What values CAN BE ENTERED                              │
│    ───────────────────────────────────────────────────     │
│    • Implemented in XdString/XdToken.enums field           │
│    • Dropdown selections in data entry UI                  │
│    • Database constraint validation                        │
│    • Fixed, small set of allowed values                    │
│    • Example: "Male, Female, Other, Unknown"               │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ 2️⃣ SEMANTIC DEFINITION                                     │
│    What does this component MEAN                           │
│    ────────────────────────────────────────────────────    │
│    • Implemented via semantic_links (M2M to PredObj)       │
│    • Ontology integration (LOINC, SNOMED, local)           │
│    • RDF triple generation                                 │
│    • Multiple vocabularies simultaneously                  │
│    • Example: Links to AdministrativeGender ValueSet       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

When to Use Each

Key Insight: Runtime enumeration answers "What can I select?", semantic links answer "What does it mean?"

4.3 FHIR Terminology Datatypes Mapping

Coding (Single Code)

FHIR Structure:

{
  "code": "8867-4",
  "system": "http://loinc.org",
  "display": "Heart rate",
  "userSelected": true
}

SDC4 Mapping Options:

Option 1: Native pred_obj (Recommended for single codes):

#### Column: observation_code
**Type**: text
**Description**: Vital sign observation code
**SemanticLinks**:
- http://loinc.org|8867-4 (Heart rate - LOINC)
- http://snomed.info/sct|364075005 (Heart rate observable - SNOMED)
- http://terminology.hl7.org/CodeSystem/observation-category|vital-signs (FHIR category)

✅ Result: Component with 3 semantic_links to 3 vocabularies

Option 2: @FHIR:Coding cluster (Only if full structure needed):

Create cluster with system, code, display, version, userSelected fields.

Decision: Use Option 1 (pred_obj) for most FHIR Coding elements.

CodeableConcept (Multiple Codes + Text)

FHIR Structure:

{
  "coding": [
    {"system": "http://hl7.org/fhir/sid/icd-10", "code": "E11.9", "display": "Type 2 DM"},
    {"system": "http://snomed.info/sct", "code": "44054006", "display": "DM Type 2"},
    {"system": "http://local.hospital.org", "code": "DIAB2", "display": "Diabetes II"}
  ],
  "text": "Type 2 Diabetes Mellitus"
}

SDC4 Mapping: Create @FHIR:CodeableConcept cluster

## Sub-Cluster: diagnosis_code
**ReuseComponent**: @FHIR:CodeableConcept
**Description**: Patient diagnosis

### Within @FHIR:CodeableConcept definition:

#### Column: coding_1_code
**Type**: text
**SemanticLinks**:
- http://hl7.org/fhir/sid/icd-10|E11.9 (Type 2 diabetes - ICD-10)

#### Column: coding_2_code
**Type**: text
**SemanticLinks**:
- http://snomed.info/sct|44054006 (Diabetes mellitus type 2 - SNOMED)

#### Column: coding_3_code
**Type**: text
**SemanticLinks**:
- http://local.hospital.org/diagnoses|DIAB2 (Local hospital code)

#### Column: text
**Type**: text
**Description**: Human-readable diagnosis description

✅ Result: Each coding has independent semantic_links - cross-vocabulary mapping within one CodeableConcept!

ValueSet References

FHIR: ValueSet URIs define sets of allowed codes

SDC4 Mapping: Combine runtime enumeration + semantic link to ValueSet

#### Column: observation_status
**Type**: text
**Enumeration**:
- registered: Initial registration
- preliminary: Early results
- final: Final verified results
- amended: Modified after final
- corrected: Corrected results
- cancelled: Cancelled observation
**SemanticLinks**:
- http://hl7.org/fhir/ValueSet/observation-status (FHIR ValueSet definition)
- http://terminology.hl7.org/CodeSystem/observation-status (CodeSystem)

✅ Result: Runtime dropdown + semantic link to FHIR ValueSet for interoperability

4.4 Advantages Over UMLS Approach

Traditional UMLS Approach:

LOINC:2339-0 → UMLS:C0428568 → SNOMED:33747003
              ↑
         Intermediate
         metathesaurus

SDC4 Direct Mapping Approach:

Component "Blood Glucose"
    ↓ rdfs:seeAlso
    ├─→ LOINC:2339-0
    ↓ skos:exactMatch
    ├─→ SNOMED:33747003
    ↓ rdf:type
    └─→ Local:GLU-001

No intermediate vocabulary!

Benefits:

1. Domain Expert Control: Modeler directly assigns semantic mappings, no vocabulary service dependency
2. No Intermediate: Direct LOINC ↔ SNOMED mapping without UMLS concepts
3. Flexible Predicates: Use appropriate RDF predicate for relationship type (exactMatch, seeAlso, etc.)
4. Local Code Integration: Hospital/organization codes alongside standard vocabularies
5. RDF Native: Generates proper RDF triples for semantic web integration
6. Multiple Relationships: One component can have different predicate types to different vocabularies

4.5 MD2PD Template Syntax

Semantic Links in Templates:

**SemanticLinks**:
- http://loinc.org|8867-4 (Heart rate)
- http://snomed.info/sct|364075005 (Heart rate observable)
- http://local.codes|HR (Local code)

Current Implementation: URIs only, predicates assigned by semantic linking service

Parsed Structure:

column.semantic_links = [
    {'uri': 'http://loinc.org|8867-4 (Heart rate)'},
    {'uri': 'http://snomed.info/sct|364075005 (Heart rate observable)'},
    {'uri': 'http://local.codes|HR (Local code)'}
]

Agent Processing: Semantic linking service creates PredObj instances with appropriate predicates

4.6 FHIR-Specific Vocabulary Integration

Major FHIR Code Systems to leverage with semantic_links:

Implementation Strategy:

• Use semantic_links to map FHIR components to all relevant code systems
• Include local hospital codes alongside standard vocabularies
• Let domain expert decide which vocabularies are authoritative
• Use appropriate RDF predicates to express relationships

Part II: Datatype Analysis (Bottom-Up)

⚠️ IMPORTANT: Before implementing any FHIR datatype, consult Part I: Holistic Architecture View to check if SDC4 already has a native pattern that matches the semantic intent. Using native SDC4 patterns reduces duplication and improves semantic alignment.

>

Key Native Patterns:

- Range/ReferenceRange → Use native ReferenceRange (M2M on XdQuantified)

- Period → Use native XdInterval or two XdTemporal fields

- Meta → Use native DM fields (created, updated, audit)

- Provenance → Use native DM.creator, DM.audit, Audit model

- Signature → Use native Attestation

- Coding (single) → Use native pred_obj (PredObj model)

>

Decision Framework: See Section 3: Native vs @FHIR Decision Framework

4. Complete FHIR Datatypes Inventory

1.1 Primitive Types (19 total)

Simple, single-value types with no child elements

Complexity: SIMPLE - All are primitive single values

Critical for Interoperability: boolean, integer, string, decimal, date, dateTime, code

Reference: https://www.hl7.org/fhir/datatypes.html#primitive

1.2 General-Purpose Datatypes (18 total)

Complex, reusable structures for common clinical patterns

1.2.1 Basic Information Structures

Structure Example - Identifier:

Cluster: Identifier
  - use: XdToken (enum: usual, official, temp, secondary)
  - type: XdToken (CodeableConcept)
  - system: XdLink (namespace URI)
  - value: XdString (actual identifier)
  - period: Period cluster
  - assigner: Reference cluster

1.2.2 Clinical Measurements

Structure Example - Quantity:

Quantity maps to XdQuantity with:
  - value: decimal magnitude
  - comparator: XdToken (enum: <, <=, >=, >)
  - unit: units string
  - system: UCUM code system URI
  - code: UCUM code

1.2.3 Content & References

⭐ IMPORTANT: For FHIR Coding/CodeableConcept, leverage SDC4's semanticlinks (predobj) system:

- Single FHIR Coding → Use native predobj with semanticlinks to multiple vocabularies (LOINC + SNOMED + local)

- FHIR CodeableConcept → Create @FHIR:CodeableConcept cluster where each coding[] element has its own semantic_links

- Multi-vocabulary mapping: One component can link to LOINC AND SNOMED AND local codes without UMLS intermediate

- Domain expert control: Modeler assigns semantic mappings directly

- See: Section 4: Vocabulary and Terminology Architecture for complete details

Structure Example - CodeableConcept (with semantic_links):

Cluster: CodeableConcept
  - coding: List of Coding clusters
    - system: XdLink (code system URI)
    - version: XdString
    - code: XdToken
    - display: XdString
    - userSelected: XdBoolean
  - text: XdString (human-readable)

Reference: https://www.hl7.org/fhir/datatypes.html#general-purpose

1.3 Metadata Types (11 total)

Specialized for resource documentation and specifications

Complexity: MEDIUM to VERY HIGH

Critical: None (mostly for metadata, not clinical data)

Reference: https://www.hl7.org/fhir/datatypes.html#metadata

1.4 Special Purpose Datatypes (8 total)

Domain-specific implementations

Structure Example - Reference:

Cluster: Reference
  - reference: XdLink (relative or absolute)
  - type: XdLink (resource type URL)
  - identifier: Identifier cluster
  - display: XdString (text description)

Structure Example - Dosage (VERY COMPLEX):

Cluster: Dosage
  - sequence: XdCount
  - text: XdString
  - additionalInstruction: CodeableConcept array
  - patientInstruction: XdString
  - timing: Timing cluster (itself complex)
  - asNeeded: XdBoolean OR CodeableConcept
  - site: CodeableConcept
  - route: CodeableConcept
  - method: CodeableConcept
  - doseAndRate: Complex sub-cluster
    - type: CodeableConcept
    - dose: Range OR Quantity
    - rate: Ratio OR Range OR Quantity
  - maxDosePerPeriod: Ratio array
  - maxDosePerAdministration: Quantity
  - maxDosePerLifetime: Quantity

Reference: https://www.hl7.org/fhir/datatypes.html#special-purpose

2. Current SDC4 Component Types in SDCStudio

Analysis from: src/dmgen/models.py

2.1 Core Components (Inherit from XdAny)

2.2 Ordered Types (Inherit from XdOrdered)

2.3 Quantified Types (Inherit from XdQuantified)

Note: All XdQuantified types have magnitude status, error, and accuracy flags.

2.4 List Types

2.5 Structural Components

2.6 Missing Types (Not Currently Implemented)

Based on FHIR analysis, SDCStudio is missing:

• XdIdentifier: Dedicated identifier type (currently uses XdString)
• XdBinary: Base64-encoded binary (uses XdFile, but not the same)
• XdMarkdown: Rich text with formatting (uses XdString)
• XdCode: Terminology codes (uses XdToken, close but not exact)

3. FHIR-to-SDC4 Mapping Strategy

3.1 Direct Mappings (Simple Types)

3.2 Complex Cluster Mappings

Identifier (CRITICAL)

MD2PD Template:

## Sub-Cluster: Identifier
**ReuseComponent**: @FHIR:Identifier
**Description**: Business identifier with namespace and validity period

### Column: use
**Type**: text
**Description**: Purpose of this identifier
**Enumeration**:
  - usual: Usual
  - official: Official
  - temp: Temporary
  - secondary: Secondary
**Constraints**:
  - required: false

### Column: type_code
**Type**: text
**Description**: Type of identifier (coded)
**Constraints**:
  - required: false

### Column: system
**Type**: url
**Description**: Namespace for the identifier value
**Examples**: http://hospital.org/patient-ids, urn:oid:2.16.840.1.113883.4.1

### Column: value
**Type**: text
**Description**: The actual identifier value
**Constraints**:
  - required: true
**Examples**: 12345, MRN-987654, SSN-123-45-6789

### Column: period_start
**Type**: date
**Description**: When identifier is/was valid from
**Constraints**:
  - required: false

### Column: period_end
**Type**: date
**Description**: When identifier is/was valid to
**Constraints**:
  - required: false

SDC4 Implementation: Create reusable Cluster with label "FHIR:Identifier"

HumanName (CRITICAL)

MD2PD Template:

## Sub-Cluster: HumanName
**ReuseComponent**: @FHIR:HumanName
**Description**: Person's name with use context and parts

### Column: use
**Type**: text
**Description**: How this name is used
**Enumeration**:
  - usual: Usual
  - official: Official
  - temp: Temporary
  - nickname: Nickname
  - anonymous: Anonymous
  - old: Old/previous
  - maiden: Maiden name
**Constraints**:
  - required: false

### Column: text
**Type**: text
**Description**: Full name as it should be displayed
**Examples**: Dr. John Smith Jr., Ms. Jane Doe

### Column: family
**Type**: text
**Description**: Family name/surname/last name
**Examples**: Smith, Doe, Johnson

### Column: given
**Type**: text
**Description**: Given names (space-separated)
**Examples**: John Michael, Jane Elizabeth

### Column: prefix
**Type**: text
**Description**: Parts before the name
**Examples**: Dr., Ms., Mr., Prof.

### Column: suffix
**Type**: text
**Description**: Parts after the name
**Examples**: Jr., III, MD, PhD

### Column: period_start
**Type**: date
**Description**: When this name was/is in use from
**Constraints**:
  - required: false

### Column: period_end
**Type**: date
**Description**: When this name was/is in use to
**Constraints**:
  - required: false

Address (CRITICAL)

MD2PD Template:

## Sub-Cluster: Address
**ReuseComponent**: @FHIR:Address
**Description**: Physical or postal address with use context

### Column: use
**Type**: text
**Description**: Purpose of this address
**Enumeration**:
  - home: Home
  - work: Work
  - temp: Temporary
  - old: Old/previous
  - billing: Billing
**Constraints**:
  - required: false

### Column: type
**Type**: text
**Description**: Postal vs physical address
**Enumeration**:
  - postal: Postal
  - physical: Physical location
  - both: Both postal and physical
**Constraints**:
  - required: false

### Column: text
**Type**: text
**Description**: Full address as displayed
**Examples**: 123 Main St, Apt 4B, Springfield, IL 62701 USA

### Column: line_1
**Type**: text
**Description**: Street address line 1
**Examples**: 123 Main Street, PO Box 456

### Column: line_2
**Type**: text
**Description**: Street address line 2 (apartment, suite, etc.)
**Examples**: Apt 4B, Suite 200

### Column: city
**Type**: text
**Description**: City name
**Examples**: Springfield, Chicago, New York

### Column: district
**Type**: text
**Description**: District/county
**Examples**: Cook County, Kings County

### Column: state
**Type**: text
**Description**: State/province/territory
**Examples**: IL, CA, NY, Ontario

### Column: postal_code
**Type**: text
**Description**: Postal or ZIP code
**Examples**: 62701, 90210, M5H 2N2

### Column: country
**Type**: text
**Description**: Country (ISO 3166 code preferred)
**Examples**: US, CA, GB, AU

### Column: period_start
**Type**: date
**Description**: When address was/is valid from
**Constraints**:
  - required: false

### Column: period_end
**Type**: date
**Description**: When address was/is valid to
**Constraints**:
  - required: false

Quantity (CRITICAL)

MD2PD Template:

## Sub-Cluster: Quantity
**ReuseComponent**: @FHIR:Quantity
**Description**: Measured amount with units and comparator

### Column: value
**Type**: decimal
**Description**: Numeric value of the measurement
**Examples**: 5.5, 120.0, 98.6

### Column: comparator
**Type**: text
**Description**: How to interpret the value
**Enumeration**:
  - <: Less than
  - <=: Less than or equal to
  - >=: Greater than or equal to
  - >: Greater than
**Constraints**:
  - required: false

### Column: unit
**Type**: text
**Description**: Unit representation (display)
**Examples**: kg, mg/dL, mmHg, celsius

### Column: system
**Type**: url
**Description**: System that defines the coded unit form
**Examples**: http://unitsofmeasure.org
**Constraints**:
  - required: false

### Column: code
**Type**: text
**Description**: Coded form of the unit (UCUM)
**Examples**: kg, mg/dL, mm[Hg], Cel
**Constraints**:
  - required: false

Implementation Note: Can map simplified version directly to XdQuantity with UCUM units.

CodeableConcept (CRITICAL)

MD2PD Template:

## Sub-Cluster: CodeableConcept
**ReuseComponent**: @FHIR:CodeableConcept
**Description**: Concept with multiple codes from different terminologies

### Column: text
**Type**: text
**Description**: Plain text representation of the concept
**Examples**: Type 2 Diabetes Mellitus, Hypertension

## Sub-Cluster: Coding
**Parent**: CodeableConcept
**Description**: Individual code from a terminology
**Cardinality**: 0..*

### Column: system
**Type**: url
**Description**: Terminology system URL
**Examples**: http://snomed.info/sct, http://loinc.org, http://hl7.org/fhir/sid/icd-10

### Column: version
**Type**: text
**Description**: Version of the code system
**Examples**: 2023-03, 2.74

### Column: code
**Type**: text
**Description**: Code value from the system
**Examples**: 44054006, 8867-4, E11.9

### Column: display
**Type**: text
**Description**: Human-readable meaning
**Examples**: Type 2 diabetes mellitus, Heart rate, Type 2 diabetes without complications

### Column: userSelected
**Type**: boolean
**Description**: Was this code selected by the user directly
**Constraints**:
  - required: false

Challenge: Repeating Coding element requires list handling or multiple row approach.

Reference (CRITICAL)

MD2PD Template:

## Sub-Cluster: Reference
**ReuseComponent**: @FHIR:Reference
**Description**: Link to another FHIR resource

### Column: reference
**Type**: url
**Description**: Literal reference (relative or absolute URI)
**Examples**: Patient/123, http://fhir.example.org/Patient/456

### Column: type
**Type**: url
**Description**: Type of resource being referenced
**Examples**: http://hl7.org/fhir/StructureDefinition/Patient

### Column: display
**Type**: text
**Description**: Text alternative for the reference
**Examples**: John Smith (MRN: 12345), Dr. Jane Doe

Simplified version - Full version includes embedded Identifier cluster.

ContactPoint (CRITICAL)

MD2PD Template:

## Sub-Cluster: ContactPoint
**ReuseComponent**: @FHIR:ContactPoint
**Description**: Phone, email, fax, or other contact details

### Column: system
**Type**: text
**Description**: Type of contact point
**Enumeration**:
  - phone: Phone
  - fax: Fax
  - email: Email
  - pager: Pager
  - url: URL
  - sms: SMS
  - other: Other
**Constraints**:
  - required: false

### Column: value
**Type**: text
**Description**: The actual contact value
**Examples**: (555) 123-4567, john.smith@example.com, http://example.com

### Column: use
**Type**: text
**Description**: Purpose of this contact point
**Enumeration**:
  - home: Home
  - work: Work
  - temp: Temporary
  - old: Old/incorrect
  - mobile: Mobile
**Constraints**:
  - required: false

### Column: rank
**Type**: integer
**Units**: priority
**Description**: Preference order (1 = highest)
**Constraints**:
  - range: [1, 999]
  - required: false

### Column: period_start
**Type**: date
**Description**: When contact point was/is valid from
**Constraints**:
  - required: false

### Column: period_end
**Type**: date
**Description**: When contact point was/is valid to
**Constraints**:
  - required: false

3.3 Specialized Cluster Mappings

Period

✅ USE NATIVE SDC4: Use XdInterval model or two XdTemporal fields instead of creating @FHIR:Period. See Section 1: SDC4 Native Patterns.

Native approach (if using XdInterval):

• Use existing XdInterval model with lower/upper temporal bounds
• Or use two separate XdTemporal fields: startdate and enddate

Old cluster approach (not recommended):

• start: XdTemporal (date or dateTime)
• end: XdTemporal (date or dateTime)

Range

✅ USE NATIVE SDC4: Use ReferenceRange model (M2M on XdQuantified) instead of creating @FHIR:Range. See Section 1.1: ReferenceRange.

Native approach:

• For Observation reference ranges: Use XdQuantified.reference_ranges M2M relationship
• ReferenceRange model includes: meaning, range (XdInterval), applies_to
• For simple ranges: Use XdInterval with lower/upper bounds

Old cluster approach (not recommended):

• low: Quantity cluster or XdQuantity
• high: Quantity cluster or XdQuantity

Timing (VERY COMPLEX)

Used for medication schedules, appointments. Requires extensive cluster with:

• event: XdTemporalList (specific times)
• code: CodeableConcept (BID, TID, QID, etc.)
• repeat sub-cluster with 15+ fields for frequency, duration, bounds, etc.

Priority: MEDIUM (healthcare-specific, very complex)

Dosage (VERY COMPLEX)

See structure example in Section 1.4 - extremely complex with nested choice types and arrays.

Priority: HIGH for medication workflows, but implement AFTER simpler types

4. Implementation Priority Recommendations

Tier 1: CRITICAL (Implement First)

These are foundational and used across ALL FHIR resources

1. Identifier - Every resource has identifiers
2. HumanName - Patient, Practitioner, Person, RelatedPerson
3. Address - Patient, Organization, Location, Practitioner
4. CodeableConcept - Diagnoses, procedures, medications, observations
5. Reference - Links between all resources
6. Quantity - All measurements, vital signs, lab results
7. ContactPoint - Contact information for persons/organizations

Estimated Effort: 3-4 weeks for all Tier 1 components

Impact: Enables 80% of common FHIR use cases

Dependencies: None - can start immediately

Success Criteria:

• All 7 components published in @FHIR project
• Example Patient demographics model created
• Documentation complete
• Test coverage >90%

Tier 2: HIGH (Implement Second)

Clinical and operational essentials

⚠️ REVISED based on holistic analysis: Period and Range use native SDC4 patterns (see Part I)

1. ~~Period~~ - ✅ Use native XdInterval or two XdTemporal fields (see Part I)
2. ~~Range~~ - ✅ Use native ReferenceRange (see Part I)
3. Coding - Individual codes (part of CodeableConcept) - ⚠️ Consider using native pred_obj for single codes (see Part I)
4. Attachment - Documents, images, reports
5. Narrative - Human-readable resource text
6. Extension - Custom fields (extensibility)
7. Money - Billing and claims

Estimated Effort: 1-2 weeks (reduced from 2-3 weeks due to native pattern usage)

Impact: Enables complete clinical documentation

Dependencies: Tier 1 (CodeableConcept for Attachment, Extension uses all types)

Success Criteria:

• All components integrated with Tier 1
• Document attachment workflows tested
• Extension mechanism validated
• Billing use cases supported

Tier 3: MEDIUM (Implement Third)

Domain-specific but common

1. Dosage - Medication orders (VERY complex!)
2. Timing - Schedules and recurrence (VERY complex!)
3. Annotation - Clinical notes
4. SampledData - Waveforms (ECG, etc.)
5. Ratio/RatioRange - Mix ratios, dilutions
6. Signature - Legal validation

Estimated Effort: 3-4 weeks (Dosage and Timing are very complex)

Impact: Enables specialized healthcare workflows

Dependencies: Tier 1 and 2 (Dosage uses CodeableConcept, Range, Ratio, Timing)

Success Criteria:

• Medication order workflow complete
• Scheduling system functional
• Clinical documentation enhanced
• Specialized measurements supported

Tier 4: LOW (Optional/Future)

Metadata and advanced features

1. Meta - Resource versioning
2. UsageContext - Applicability contexts
3. ContactDetail - Implementation guide contacts
4. RelatedArtifact - Citations, documentation
5. All other metadata types

Estimated Effort: 1-2 weeks

Impact: Metadata and advanced interoperability

Dependencies: All previous tiers

Success Criteria:

• Complete FHIR R4 datatype coverage
• Metadata workflows documented
• Advanced features available

5. Strategic Recommendations

5.1 Component Reuse Architecture

Create FHIR Library Project:

Project Name: FHIR
Description: Fast Healthcare Interoperability Resources (HL7 FHIR R4)
Version: R4 (4.0.1)
Published: true
Public: true
Creator: SDCStudio Team
Standards: HL7 FHIR R4, ISO 13606

Metadata Fields:

• dc_subject: "Healthcare Interoperability, FHIR, HL7"
• dc_source: "https://www.hl7.org/fhir/datatypes.html"
• dc_rights: "Content from HL7 FHIR specification (Creative Commons Attribution)"
• dc_publisher: "HL7 International"

Populate with Tier 1 Components:

• Each complex type becomes a published Cluster
• Primitive mappings documented in templates
• Version alignment with FHIR R4 (4.0.1)
• All components marked as reusable

Usage in Templates:

## Sub-Cluster: Patient Name
**ReuseComponent**: @FHIR:HumanName
**Description**: Patient's legal name

## Sub-Cluster: Patient Address
**ReuseComponent**: @FHIR:Address
**Description**: Patient's home address

## Sub-Cluster: Medical Record Number
**ReuseComponent**: @FHIR:Identifier
**Description**: Hospital-assigned patient MRN

5.2 Template Generation Strategy

Create MD2PD FHIR Templates Directory Structure:

docs/
├── templates/
│   ├── fhir/
│   │   ├── README.md (index of all FHIR templates)
│   │   ├── datatypes/
│   │   │   ├── fhir-identifier.md
│   │   │   ├── fhir-humanname.md
│   │   │   ├── fhir-address.md
│   │   │   ├── fhir-contactpoint.md
│   │   │   ├── fhir-codeableconcept.md
│   │   │   ├── fhir-quantity.md
│   │   │   ├── fhir-reference.md
│   │   │   └── ... (all other datatypes)
│   │   ├── resources/
│   │   │   ├── fhir-patient.md
│   │   │   ├── fhir-observation.md
│   │   │   ├── fhir-condition.md
│   │   │   ├── fhir-procedure.md
│   │   │   ├── fhir-medication-request.md
│   │   │   ├── fhir-encounter.md
│   │   │   └── ... (common resources)
│   │   └── examples/
│   │       ├── patient-demographics.md
│   │       ├── vital-signs-observation.md
│   │       └── medication-order.md

Template Files to Create:

1. FHIR Datatype Templates (for building reusable components):
   • One MD2PD template per FHIR datatype
   • Upload to create @FHIR:ComponentName clusters
   • Published and marked as library components
2. FHIR Resource Templates (for actual data models):
   • Complete resource definitions using @FHIR components
   • Patient, Observation, Condition, Procedure, etc.
   • Real-world clinical scenarios
3. FHIR Example Templates (for learning):
   • Step-by-step examples
   • Common use cases documented
   • Best practices demonstrated

README.md Contents:

# FHIR Templates for SDCStudio

Templates for building HL7 FHIR R4 compliant data models.

## Quick Start

1. Upload datatype templates to create @FHIR library components
2. Use resource templates to build FHIR-based data models
3. Reuse @FHIR components with **ReuseComponent**: @FHIR:ComponentName

## Template Categories

- **datatypes/**: Reusable FHIR datatype components
- **resources/**: Complete FHIR resource models
- **examples/**: Learning examples and common patterns

## Priority Components (Tier 1)

Start with these critical datatypes:
- Identifier - Business identifiers
- HumanName - Person names
- Address - Physical/postal addresses
- ContactPoint - Phone/email/fax
- CodeableConcept - Coded concepts
- Quantity - Measurements
- Reference - Resource links

5.3 Type Mapping Enhancement

Extend Template Parser with FHIR-Aware Mapping:

Location: src/md2pd/agents/templateparseragent.py

# Add FHIR primitive type mappings
FHIR_TYPE_MAPPINGS = {
    'fhir:boolean': ('XdBoolean', {}),
    'fhir:integer': ('XdCount', {'units': 'count'}),
    'fhir:positiveInt': ('XdCount', {'min_magnitude': 1, 'units': 'count'}),
    'fhir:unsignedInt': ('XdCount', {'min_magnitude': 0, 'units': 'count'}),
    'fhir:decimal': ('XdQuantity', {}),
    'fhir:string': ('XdString', {}),
    'fhir:code': ('XdToken', {'requires_enumeration': True}),
    'fhir:uri': ('XdLink', {}),
    'fhir:url': ('XdLink', {}),
    'fhir:canonical': ('XdLink', {'add_version_field': True}),
    'fhir:date': ('XdTemporal', {'allow_date': True}),
    'fhir:dateTime': ('XdTemporal', {'allow_datetime': True}),
    'fhir:time': ('XdTemporal', {'allow_time': True}),
    'fhir:instant': ('XdTemporal', {'allow_datetime': True, 'precision': 'millisecond'}),
    'fhir:base64Binary': ('XdFile', {'encoding': 'base64'}),
    'fhir:id': ('XdString', {'max_length': 64}),
    'fhir:uuid': ('XdString', {'format': 'uuid'}),
    'fhir:oid': ('XdString', {'format': 'oid'}),
    'fhir:markdown': ('XdString', {'allow_formatting': True}),
    'fhir:integer64': ('XdDouble', {}),
}

def _map_fhir_type(self, type_str: str) -> Tuple[str, Dict[str, Any], str]:
    """
    Map FHIR datatype to SDC4 type with configuration.

    Args:
        type_str: Type string from template (may include 'fhir:' prefix)

    Returns:
        Tuple of (sdc4_type, config_dict, notes)
    """
    if type_str.lower().startswith('fhir:'):
        mapping = FHIR_TYPE_MAPPINGS.get(type_str.lower())
        if mapping:
            sdc4_type, config = mapping
            notes = f"FHIR type {type_str} mapped to {sdc4_type}"
            return sdc4_type, config, notes

    # Fall back to standard type mapping
    return self._map_user_friendly_type(type_str)

def _apply_fhir_config(self, column: ColumnInfo, config: Dict[str, Any]):
    """Apply FHIR-specific configuration to column."""
    if 'units' in config:
        column.units = config['units']
    if 'min_magnitude' in config:
        column.range_values = {'min': config['min_magnitude']}
    if 'requires_enumeration' in config and config['requires_enumeration']:
        # Add validation to ensure enumeration is provided
        pass
    # ... etc

Add FHIR Type Detection:

def _detect_fhir_context(self, template_content: str) -> bool:
    """
    Detect if template is using FHIR datatypes.

    Checks for:
    - **ReuseComponent**: @FHIR:* references
    - Type: fhir:* declarations
    - FHIR-specific keywords or metadata
    """
    if '@FHIR:' in template_content:
        return True
    if 'fhir:' in template_content.lower():
        return True
    return False

5.4 Validation and Constraints

FHIR-Specific Validation Rules:

1. Identifier.system must be valid URI
2. Quantity.system should be UCUM (http://unitsofmeasure.org)
3. Coding.system must be valid terminology system URI (SNOMED, LOINC, etc.)
4. Address.country should be ISO 3166 code
5. ContactPoint.system limited to defined enumeration
6. HumanName.use limited to defined enumeration

Implementation:

Location: src/md2pd/agents/templateparseragent.py

def _validate_fhir_constraints(self, column: ColumnInfo, validation_results: Dict):
    """
    Apply FHIR-specific validation rules.

    Args:
        column: Column to validate
        validation_results: Dictionary to accumulate validation messages
    """
    if column.reuse_project != 'FHIR':
        return

    # Identifier.system validation
    if column.reuse_label == 'Identifier' and column.name == 'system':
        if column.data_type != 'XdLink':
            validation_results['warnings'].append(
                f"FHIR Identifier.system should be XdLink (URI), got {column.data_type}"
            )

    # Quantity.system validation
    if column.reuse_label == 'Quantity' and column.name == 'system':
        if not column.examples or 'unitsofmeasure.org' not in str(column.examples):
            validation_results['suggestions'].append(
                "FHIR Quantity.system should typically be 'http://unitsofmeasure.org' for UCUM units"
            )

    # CodeableConcept.coding.system validation
    if column.reuse_label in ['CodeableConcept', 'Coding'] and column.name == 'system':
        if column.data_type != 'XdLink':
            validation_results['warnings'].append(
                f"FHIR Coding.system should be XdLink (URI), got {column.data_type}"
            )

    # ... additional FHIR-specific validations

Add to Keyword Validation:

FHIR_SPECIFIC_KEYWORDS = {
    'FHIR Version',
    'Resource Type',
    'Profile URL',
    'Must Support',
    'Binding Strength',
    'Value Set'
}

# These are documentation keywords allowed in FHIR templates
VALID_FHIR_DOC_KEYWORDS = VALID_DOC_KEYWORDS | FHIR_SPECIFIC_KEYWORDS

5.5 Documentation and Training

Create Comprehensive FHIR Documentation:

1. User Guide (docs/users/fhir-integration-guide.md)

Contents:

• What is FHIR and why use it
• FHIR datatypes overview
• How to use @FHIR components in SDCStudio
• Step-by-step tutorial: Building a Patient model
• Common FHIR patterns and recipes
• Troubleshooting guide

Structure:

# FHIR Integration Guide for SDCStudio Users

## What is FHIR?

HL7 FHIR (Fast Healthcare Interoperability Resources) is a standard for exchanging healthcare information electronically...

## Why Use FHIR Datatypes in SDCStudio?

- **Interoperability**: Models compatible with FHIR systems
- **Standards-based**: Leverage established healthcare patterns
- **Reusability**: Use pre-built @FHIR components
- **Quality**: Validated structures from HL7

## Getting Started

### Step 1: Understanding @FHIR Components

SDCStudio provides reusable FHIR components via the @FHIR project...

### Step 2: Building Your First FHIR Model

Let's create a simple Patient demographics model...

### Step 3: Using Component Reuse

Instead of defining everything from scratch, reuse @FHIR components...

2. Developer Guide (docs/dev/FHIRDATATYPEMAPPING.md)

Contents:

• Technical mapping details (FHIR → SDC4)
• Implementation patterns
• Extension points for custom FHIR types
• Testing strategies
• Code examples

Structure:

# FHIR Datatype Mapping - Developer Guide

## Architecture Overview

FHIR integration in SDCStudio follows these principles:
1. Component reuse via @FHIR project
2. Type mapping in template parser
3. Validation at parsing and agent stages
4. XSD generation with FHIR compatibility

## Primitive Type Mappings

| FHIR Primitive | SDC4 Type | Config | Notes |
|----------------|-----------|--------|-------|
| boolean | XdBoolean | - | Direct mapping |
| integer | XdCount | units="count" | Default units |
...

## Complex Type Implementation

### Cluster-Based Mapping

FHIR complex types map to SDC4 Clusters with specific component patterns...

### Repeating Elements

FHIR supports arrays of complex types (e.g., CodeableConcept.coding). Current approach...

### Choice Types (value[x])

FHIR choice types represented as union clusters with cardinality constraints...

## Adding New FHIR Types

To add a new FHIR datatype to SDCStudio:
1. Create MD2PD template in `docs/templates/fhir/datatypes/`
2. Upload to create @FHIR component
3. Add type mapping if primitive
4. Add validation rules
5. Create tests
6. Update documentation

3. Template Catalog (docs/templates/fhir/README.md)

Contents:

• Index of all FHIR templates
• Quick reference for component reuse
• Common patterns and recipes
• Version compatibility matrix

Structure:

# FHIR Template Catalog

Complete collection of FHIR R4 datatype and resource templates for SDCStudio.

## Datatypes (50+ templates)

### Tier 1: Critical (Start Here)

| Component | Template | Complexity | Use Cases |
|-----------|----------|------------|-----------|
| Identifier | `fhir-identifier.md` | Medium | Patient IDs, MRNs, SSNs |
| HumanName | `fhir-humanname.md` | High | Patient/provider names |
| Address | `fhir-address.md` | High | Patient/facility addresses |
...

## Resources (10+ templates)

| Resource | Template | Based On | Purpose |
|----------|----------|----------|---------|
| Patient | `fhir-patient.md` | Demographics | Patient master record |
| Observation | `fhir-observation.md` | Vital Signs, Labs | Clinical measurements |
...

## Quick Reference

### Reuse Syntax

ReuseComponent: @FHIR:Identifier

ReuseComponent: @FHIR:HumanName

ReuseComponent: @FHIR:Address

### Common Patterns

**Patient Demographics Pattern**:
- Root Cluster: Patient
  - @FHIR:Identifier (MRN)
  - @FHIR:HumanName
  - @FHIR:Address
  - @FHIR:ContactPoint (phone, email)
  - Birth date
  - Gender

6. Critical Considerations and Challenges

6.1 Repeating Elements (Arrays)

Challenge: FHIR has many repeating elements that form arrays.

Examples:

• CodeableConcept.coding is an array of Coding objects
• Patient.identifier is an array of Identifier objects
• Patient.name is an array of HumanName objects
• Patient.address is an array of Address objects

Current SDCStudio Support:

• ✅ List types exist (XdStringList, XdIntegerList, XdDecimalList, etc.)
• ❌ Complex cluster arrays are NOT directly supported
• ❌ Cannot have "list of Clusters" in current architecture

Impact:

• Cannot fully represent FHIR resources in single-row format
• Must choose between fidelity and simplicity

Solutions:

Option A: Multiple Rows with Parent Relationship (MVP)

Patient (Row 1):
  - id: PAT-001

Identifier (Row 2):
  - parent_id: PAT-001
  - use: official
  - system: http://hospital.org/mrn
  - value: MRN-12345

Identifier (Row 3):
  - parent_id: PAT-001
  - use: usual
  - system: urn:oid:2.16.840.1.113883.4.1
  - value: 123-45-6789

Pros:

• Works with current architecture
• Preserves full FHIR structure
• Supports unlimited repetitions

Cons:

• More complex data model
• Requires join logic
• Not obvious to users

Option B: JSON Serialization (Simple but Lossy)

Patient (Row 1):
  - id: PAT-001
  - identifiers_json: '[{"use":"official","system":"...","value":"MRN-12345"},...]'

Pros:

• Single row representation
• Simple to implement

Cons:

• Loses structured validation
• Cannot query individual identifiers
• Not true semantic representation

Option C: Cluster Array Support (Best, but Requires Development)

Patient (Row 1):
  - id: PAT-001
  - identifiers: [Identifier[], min=1, max=*]
    - identifier[0]: @FHIR:Identifier
    - identifier[1]: @FHIR:Identifier

Pros:

• True FHIR representation
• Clean data model
• Maintains structure

Cons:

• Requires significant SDCStudio enhancement
• Changes to Cluster model
• Changes to XSD generation
• 3-4 weeks development time

Recommendation:

• Start with Option A for MVP (works today)
• Document limitation in templates
• Plan Option C for SDCStudio 4.1 or 4.2
• Provide migration path when ready

6.2 Choice Types (value[x])

Challenge: FHIR uses "choice types" where a single field can be one of multiple types.

Example: Observation.value[x] can be:

• valueQuantity (measurement)
• valueCodeableConcept (coded value)
• valueString (text)
• valueBoolean (yes/no)
• valueInteger (count)
• valueRange (low-high)
• valueRatio (numerator/denominator)
• valueSampledData (waveform)
• valueTime (time)
• valueDateTime (timestamp)
• valuePeriod (time range)

FHIR Rules:

• Exactly ONE value[x] type must be present
• Cannot have multiple value types simultaneously
• Choice is made at data instance level

Current SDCStudio Support:

• ❌ No native "choice type" or "union type" support
• Cardinality is per-component, not per-group

Solutions:

Option A: Union Cluster with Cardinality (Recommended)

## Sub-Cluster: Observation Value
**Description**: Value of observation - choose ONE type

### Column: value_quantity
**Type**: decimal
**Units**: varies
**Cardinality**: 0..1
**Business Rules**: If present, other value types must be absent

### Column: value_codeable_concept
**ReuseComponent**: @FHIR:CodeableConcept
**Cardinality**: 0..1
**Business Rules**: If present, other value types must be absent

### Column: value_string
**Type**: text
**Cardinality**: 0..1
**Business Rules**: If present, other value types must be absent

### Column: value_boolean
**Type**: boolean
**Cardinality**: 0..1
**Business Rules**: If present, other value types must be absent

**Business Rules**: Exactly one value_* field must be populated

Pros:

• Works with current SDCStudio
• Documents the choice explicitly
• Can add validation rules

Cons:

• Verbose (many null columns)
• Business rule enforcement not automatic
• Schema validation challenging

Option B: Separate Clusters per Type (Alternative)

## Sub-Cluster: Quantity Observation
**Description**: Observation with numeric value
- value: @FHIR:Quantity

## Sub-Cluster: Coded Observation
**Description**: Observation with coded value
- value: @FHIR:CodeableConcept

## Sub-Cluster: Text Observation
**Description**: Observation with text value
- value: XdString

Pros:

• Clear and simple
• No null columns
• Type-specific validation

Cons:

• Creates multiple nearly-identical models
• User must choose model upfront
• Harder to mix types in dataset

Recommendation:

• Use Option A for flexible models
• Use Option B for type-specific templates
• Provide both approaches in template library

6.3 Terminology Binding

Challenge: FHIR datatypes often bind to ValueSets (controlled terminologies).

Examples:

• Identifier.use → IdentifierUse ValueSet (4 codes)
• HumanName.use → NameUse ValueSet (7 codes)
• Address.use → AddressUse ValueSet (5 codes)
• Address.type → AddressType ValueSet (3 codes)
• ContactPoint.system → ContactPointSystem ValueSet (7 codes)
• ContactPoint.use → ContactPointUse ValueSet (5 codes)
• Quantity.system → UCUM system (http://unitsofmeasure.org)

FHIR Binding Strengths:

• Required: Must use codes from this ValueSet
• Extensible: Should use codes from this ValueSet, but can extend
• Preferred: Recommended to use, but not enforced
• Example: Example codes only, use whatever you need

Solution: Pre-populate Enumerations in FHIR Component Templates

Implementation:

### Column: use
**Type**: text
**Description**: Purpose of this identifier
**Enumeration**:
  - usual: Usual
  - official: Official
  - temp: Temporary
  - secondary: Secondary
**Semantic Links**:
  - http://hl7.org/fhir/ValueSet/identifier-use
**Constraints**:
  - required: false
**Business Rules**: FHIR required binding - must use one of these codes

Benefits:

• Users get correct codes automatically
• Validation catches invalid codes
• Links to official FHIR ValueSets
• Self-documenting

Maintenance:

• Must update when FHIR ValueSets change
• Version in template metadata
• Provide update process

6.4 Extensions

Challenge: FHIR allows arbitrary extensions to ANY datatype or resource.

Purpose:

• Add custom fields not in base FHIR
• Profile-specific data (US Core, UK Core, etc.)
• Organization-specific information

Structure:

Extension:
  - url: URI identifying the extension definition
  - value[x]: Value of the extension (choice type)

Solution: Provide Reusable Extension Cluster Template

Template (fhir-extension.md):

## Sub-Cluster: Extension
**ReuseComponent**: @FHIR:Extension
**Description**: Optional extension to any FHIR element
**Cardinality**: 0..*

### Column: url
**Type**: url
**Description**: Identifies the meaning of the extension
**Constraints**:
  - required: true
**Examples**: http://hl7.org/fhir/StructureDefinition/patient-birthPlace

### Column: value_string
**Type**: text
**Description**: Value as string
**Cardinality**: 0..1

### Column: value_boolean
**Type**: boolean
**Description**: Value as boolean
**Cardinality**: 0..1

### Column: value_integer
**Type**: integer
**Description**: Value as integer
**Cardinality**: 0..1

### Column: value_decimal
**Type**: decimal
**Description**: Value as decimal
**Cardinality**: 0..1

### Column: value_uri
**Type**: url
**Description**: Value as URI
**Cardinality**: 0..1

### Column: value_date
**Type**: date
**Description**: Value as date
**Cardinality**: 0..1

### Column: value_datetime
**Type**: datetime
**Description**: Value as datetime
**Cardinality**: 0..1

**Business Rules**: Exactly one value_* field must be populated if extension is present

Usage in Patient Model:

## Sub-Cluster: Patient Extensions
**Description**: Custom patient data

### Extension: Birth Place
**ReuseComponent**: @FHIR:Extension
**url**: http://hl7.org/fhir/StructureDefinition/patient-birthPlace
**value_string**: City/country of birth

### Extension: Race
**ReuseComponent**: @FHIR:Extension
**url**: http://hl7.org/fhir/us/core/StructureDefinition/us-core-race
**value_codeable_concept**: Race category

Recommendation:

• Provide Extension as reusable component
• Document common extensions
• Support US Core extensions out of box

6.5 Version Compatibility

Challenge: FHIR has multiple versions with breaking changes.

Versions:

• DSTU2 (2015) - Deprecated
• STU3 (2017) - Legacy, still used
• R4 (2019) - Current normative version ⭐
• R5 (2023) - Next major version

Key Differences:

• Datatype names changed (e.g., Coding vs Code)
• Structure changes (e.g., Quantity comparator)
• New datatypes in R5
• Deprecated types

Recommendation:

• Start with FHIR R4 (most widely adopted)
• Version in project metadata: "FHIR R4 (4.0.1)"
• Plan for R5 migration when it gains adoption
• Document version in all templates
• Separate projects if supporting multiple versions

Project Naming:

• @FHIR (R4 by default)
• @FHIR-R5 (when R5 support added)
• @FHIR-STU3 (if legacy support needed)

6.6 Cardinality and Must Support

FHIR Cardinality:

• 0..1 - Optional, single value
• 1..1 - Required, single value
• 0..* - Optional, repeating (array)
• 1..* - Required, repeating (array, at least one)

Must Support Flag:

• Elements marked "Must Support" in profiles
• Systems must be able to store/retrieve these elements
• Not same as "required" - can be empty, but must handle

SDCStudio Mapping:

• Use Constraints: required: true/false
• Use Cardinality in cluster descriptions
• Add Business Rules for Must Support
• Document in component descriptions

Example:

### Column: identifier
**ReuseComponent**: @FHIR:Identifier
**Cardinality**: 0..*
**Description**: Patient identifiers (MRN, SSN, etc.)
**Must Support**: true
**Business Rules**: System must support storing and retrieving patient identifiers

7. Implementation Roadmap

Phase 1: Foundation (Weeks 1-4)

Goal: Establish FHIR infrastructure and critical components

Week 1: Setup and Planning

Tasks:

• [ ] Create @FHIR project in SDCStudio
  • Name: "FHIR"
  • Description: "Fast Healthcare Interoperability Resources (HL7 FHIR R4)"
  • Version: "R4 (4.0.1)"
  • Published: true, Public: true
• [ ] Set up documentation structure
  • Create docs/FHIR/ directory
  • Copy this analysis document
  • Create template directories
• [ ] Review and finalize Tier 1 component list
• [ ] Assign development resources

Deliverables:

• @FHIR project live in SDCStudio
• Documentation structure in place
• Development team briefed

Week 2: Tier 1 Components (Part 1)

Components to Implement:

1. ✅ Identifier
2. ✅ HumanName
3. ✅ Address

Tasks per Component:

• [ ] Create MD2PD template in docs/templates/fhir/datatypes/
• [ ] Upload template to SDCStudio
• [ ] Publish as @FHIR:ComponentName
• [ ] Test reuse in example model
• [ ] Document usage examples
• [ ] Add validation rules

Deliverables:

• 3 FHIR components published
• 3 template files created
• Test models validating reuse

Week 3: Tier 1 Components (Part 2)

Components to Implement:

1. ✅ ContactPoint
2. ✅ Quantity
3. ✅ Reference

Tasks: (Same as Week 2)

Deliverables:

• 6 FHIR components published (cumulative)
• 6 template files created
• Growing test suite

Week 4: Tier 1 Completion and Integration

Components to Implement:

1. ✅ CodeableConcept (complex - needs Coding too)

Integration Tasks:

• [ ] Create example Patient demographics model
  • Use all 7 Tier 1 components
  • Test component reuse
  • Validate XSD generation
• [ ] Write FHIR Integration Guide (user docs)
• [ ] Write FHIR Datatype Mapping Guide (dev docs)
• [ ] Create template catalog README
• [ ] Set up test suite for FHIR mappings

Deliverables:

• ✅ All 7 Tier 1 components published
• ✅ Example Patient model functional
• ✅ Documentation complete
• ✅ Test coverage >90%

Phase 1 Success Criteria:

• [ ] 80% of common FHIR use cases supported
• [ ] Patient demographics fully modeled
• [ ] Component reuse validated
• [ ] Documentation comprehensive
• [ ] Zero data loss in FHIR→SDC4 conversion

Phase 2: Expansion (Weeks 5-8)

Goal: Enable complete clinical documentation

Week 5: Tier 2 Components (Part 1)

⚠️ REVISED: Period and Range now use native SDC4 patterns (see Part I)

Components to Implement:

1. ~~Period~~ - ✅ Use native XdInterval or two XdTemporal fields
2. ~~Range~~ - ✅ Use native ReferenceRange
3. ✅ Coding (or use native pred_obj for single codes)
4. ✅ Attachment (moved from Week 6)

Tasks:

• Document native pattern usage for Period and Range (no component creation needed)
• Implement Coding component (or document pred_obj usage)
• Implement Attachment component
• Update FHIR mapping guide with native pattern examples

Deliverables:

• 9 FHIR components published (cumulative) - Reduced from 10 due to native patterns
• Native pattern usage documented
• CodeableConcept integration validated

Week 6: Tier 2 Components (Part 2)

⚠️ REVISED: Attachment moved to Week 5

Components to Implement:

1. ✅ Narrative
2. ✅ Extension
3. ✅ Money (moved from Week 7)

Tasks:

• Focus on Extension (critical for profiles)
• Validate Narrative with XHTML
• Implement Money for billing/claims

Deliverables:

• 12 FHIR components published (cumulative) - Reduced from 13 (Period/Range use native)
• Extension mechanism validated
• Billing use cases supported

Week 7: Resource Templates and Native Pattern Documentation

⚠️ REVISED: Money moved to Week 6, focus on resource templates and native patterns

Resource Templates:

• [ ] Create FHIR Patient template (complete resource)
  • Uses native DM metadata for Meta
  • Uses @FHIR:Identifier, @FHIR:HumanName, @FHIR:Address
• [ ] Create FHIR Observation template (vital signs)
  • Uses native ReferenceRange for reference ranges
  • Uses native pred_obj for codes
  • Uses @FHIR:CodeableConcept for composite codes
• [ ] Create FHIR Condition template (diagnoses)
  • Uses native XdInterval for onset/abatement periods

Documentation Tasks:

• [ ] Document all native pattern mappings
• [ ] Create examples showing ReferenceRange usage
• [ ] Create examples showing pred_obj for LOINC/SNOMED codes

Deliverables:

• 12 FHIR components published (cumulative) - Reduced from 14 (Period/Range use native)
• 3 FHIR resource templates created with native patterns
• Native pattern documentation complete

Week 8: Enhanced Validation and Testing

Tasks:

• [ ] Implement FHIR-specific validation rules
  • Identifier.system URI validation
  • Quantity.system UCUM validation
  • Terminology binding checks
• [ ] Enhance template parser with FHIR type mappings
• [ ] Add FHIR examples to Obsidian template
• [ ] Create comprehensive test suite
  • Unit tests for each component
  • Integration tests for resources
  • XSD validation tests

Deliverables:

• Enhanced validation in place
• Template parser FHIR-aware
• Test coverage >95%
• Obsidian integration complete

Phase 2 Success Criteria:

• [ ] Complete clinical documentation supported
• [ ] Document attachment workflows functional
• [ ] Extension mechanism working
• [ ] Billing use cases supported
• [ ] All validation rules implemented

Phase 3: Specialization (Weeks 9-12)

Goal: Enable specialized healthcare workflows

Week 9: Planning and Analysis

Tasks:

• [ ] Detailed analysis of Dosage datatype (VERY COMPLEX)
• [ ] Detailed analysis of Timing datatype (VERY COMPLEX)
• [ ] Design cluster array support (if implementing Option C)
• [ ] Review medication workflow requirements

Deliverables:

• Dosage implementation plan
• Timing implementation plan
• Cluster array design (if proceeding)

Week 10: Tier 3 Complex Components (Part 1)

Components to Implement:

1. ✅ Dosage (VERY COMPLEX)

Tasks:

• [ ] Create comprehensive Dosage template
• [ ] Handle nested choice types
• [ ] Implement doseAndRate sub-cluster
• [ ] Test with medication order scenarios

Deliverables:

• Dosage component published
• Medication order template created
• Complexity documented

Week 11: Tier 3 Complex Components (Part 2)

Components to Implement:

1. ✅ Timing (VERY COMPLEX)

Tasks:

• [ ] Create comprehensive Timing template
• [ ] Implement repeat sub-cluster
• [ ] Handle frequency and duration calculations
• [ ] Test with appointment scheduling

Deliverables:

• Timing component published
• Scheduling template created
• Complex recurrence patterns supported

Week 12: Tier 3 Remaining Components

Components to Implement:

1. ✅ Annotation
2. ✅ SampledData
3. ✅ Ratio/RatioRange
4. ✅ Signature

Tasks:

• Implement remaining Tier 3 components
• Focus on SampledData for waveforms (ECG, etc.)
• Validate Signature for legal requirements

Resource Templates:

• [ ] Create FHIR MedicationRequest template
• [ ] Create FHIR Appointment template
• [ ] Create FHIR DiagnosticReport template (with Attachment)

Deliverables:

• 20 FHIR components published (cumulative)
• 6+ FHIR resource templates total
• Specialized workflows demonstrated

Phase 3 Success Criteria:

• [ ] Medication order workflow complete
• [ ] Scheduling system functional
• [ ] Clinical documentation enhanced
• [ ] Waveform data supported
• [ ] Legal signature capability

Phase 4: Polish (Weeks 13-16)

Goal: Complete FHIR R4 coverage and professional polish

Week 13: Tier 4 Metadata Components

Components to Implement:

1. ✅ Meta
2. ✅ UsageContext
3. ✅ ContactDetail
4. ✅ RelatedArtifact
5. ✅ All other metadata types

Tasks:

• Implement remaining metadata components
• Focus on resource versioning (Meta)
• Context and applicability (UsageContext)

Deliverables:

• 30+ FHIR components published
• Metadata workflows documented

Week 14: Comprehensive Template Library

Tasks:

• [ ] Create 5+ additional FHIR resource templates
  • Procedure
  • Encounter
  • AllergyIntolerance
  • Immunization
  • CarePlan
• [ ] Create example templates for common scenarios
  • Emergency department visit
  • Primary care encounter
  • Medication reconciliation
• [ ] Update all templates to use latest components

Deliverables:

• 10+ FHIR resource templates
• 5+ example scenarios
• Complete template catalog

Week 15: FHIR Interoperability Testing

Tasks:

• [ ] Test XSD generation against FHIR sample data
• [ ] Validate XML instances with FHIR validators
• [ ] Test JSON-LD output with FHIR RDF representations
• [ ] Profile testing (US Core, UK Core, etc.)
• [ ] Performance benchmarks
• [ ] Load testing with large datasets

Deliverables:

• Interoperability test results
• Conformance validation
• Performance benchmarks
• Any bug fixes required

Week 16: Documentation and Training

Tasks:

• [ ] Finalize all user documentation
• [ ] Create video tutorials
• [ ] Write best practices guide
• [ ] Create quick reference cards
• [ ] Prepare training materials
• [ ] Write blog posts/articles

Deliverables:

• Complete documentation suite
• Training materials ready
• Marketing materials prepared
• Release announcement draft

Phase 4 Success Criteria:

• [ ] Full FHIR R4 datatype coverage
• [ ] Comprehensive template library
• [ ] Interoperability validated
• [ ] Performance acceptable
• [ ] Documentation complete
• [ ] Training materials ready

Post-Implementation: Maintenance and Evolution

Ongoing Tasks:

• [ ] Monitor FHIR R4 errata and updates
• [ ] Track FHIR R5 adoption
• [ ] User feedback incorporation
• [ ] Bug fixes and refinements
• [ ] New use case templates
• [ ] Profile support expansion (US Core, IPS, etc.)

Future Enhancements:

• [ ] Cluster array support (if not in Phase 3)
• [ ] FHIR R5 migration
• [ ] Advanced validation (FHIRPath, FHIR IG Publisher)
• [ ] Direct FHIR API integration
• [ ] FHIR Bulk Data support
• [ ] CDS Hooks integration

8. Success Metrics

⚠️ REVISED based on holistic analysis: Reduced component creation needs by leveraging native SDC4 patterns

8.1 Implementation Success Metrics

Component Coverage (REVISED):

• [ ] 50+ FHIR datatypes mapped to SDC4 (88% coverage) - Including native patterns
• [ ] ~12 reusable FHIR component clusters published - Reduced from 20 (Period, Range use native)
• [ ] 10+ complete FHIR resource templates created using native patterns
• [ ] Tier 1 (7 critical components) 100% complete
• [ ] Tier 2 (5 components + 2 native patterns documented) 100% complete - Revised from 7
• [ ] Tier 3 (6 specialized components) 80% complete

Native Pattern Usage:

• [ ] ReferenceRange usage documented with examples
• [ ] XdInterval usage for FHIR Period documented
• [ ] DM metadata mapping to FHIR Meta documented
• [ ] pred_obj usage for FHIR Coding documented
• [ ] All native patterns validated with real FHIR resources

Quality Metrics:

• [ ] Zero data loss in FHIR-to-SDC4 conversion
• [ ] XSD generation compatible with FHIR profiles
• [ ] XML instances validate against FHIR schemas
• [ ] JSON-LD output maps correctly to FHIR RDF
• [ ] Test coverage >95% for FHIR components
• [ ] Documentation coverage 100%

Performance Metrics:

• [ ] Template parsing <500ms for FHIR templates
• [ ] Component reuse lookup <100ms
• [ ] XSD generation <2s for complex FHIR resources
• [ ] Can handle Patient resource with 50+ fields
• [ ] Supports datasets with 1000+ FHIR instances

8.2 User Adoption Metrics

Ease of Use:

• [ ] Healthcare users can build FHIR-compliant models in <1 hour
• [ ] 90%+ user satisfaction with FHIR component reuse
• [ ] 50% reduction in modeling time vs. manual creation
• [ ] <5 minute learning curve for @FHIR:Component syntax
• [ ] Users successfully create Patient model on first try

Usage Metrics:

• [ ] 20+ users actively using @FHIR components
• [ ] 50+ FHIR-based data models created
• [ ] 10+ organizations using FHIR integration
• [ ] 100+ XSD/XML exports using FHIR components
• [ ] Template downloads >200

Support Metrics:

• [ ] <24 hour response to FHIR-related questions
• [ ] <3 bug reports per component on average
• [ ] 95%+ bug fix rate within 1 week
• [ ] User documentation rated 4.5/5 or higher
• [ ] <5% of FHIR component usage requires support

8.3 Interoperability Metrics

Standards Compliance:

• [ ] 100% FHIR R4 primitive type coverage
• [ ] 90%+ FHIR R4 complex type coverage
• [ ] Compatible with US Core profiles
• [ ] Compatible with International Patient Summary (IPS)
• [ ] Passes HL7 FHIR validator tests

Data Exchange:

• [ ] Generated XSDs validate against FHIR sample data
• [ ] Can round-trip FHIR JSON → SDCStudio → XSD → FHIR JSON
• [ ] XML instances accepted by FHIR servers (HAPI FHIR, etc.)
• [ ] RDF triples validate in FHIR ontologies
• [ ] Supports FHIR Bulk Data format

Integration:

• [ ] Works with FHIR IG Publisher
• [ ] Compatible with FHIR Profiling tools
• [ ] Supports CQL/FHIRPath expressions
• [ ] Can import FHIR StructureDefinitions
• [ ] Can export to FHIR StructureDefinitions

8.4 Business Impact Metrics

Market Position:

• [ ] SDCStudio recognized as FHIR-capable tool
• [ ] Featured in HL7 ecosystem tools
• [ ] Healthcare organizations requesting FHIR support
• [ ] Conference presentations on FHIR integration
• [ ] Publications in health IT journals

ROI Metrics:

• [ ] 10+ healthcare customers using FHIR features
• [ ] 25% increase in healthcare market share
• [ ] 5+ case studies of FHIR implementations
• [ ] Positive return on 16-week investment within 6 months
• [ ] FHIR integration cited in 50%+ new sales

Community Metrics:

• [ ] 5+ community-contributed FHIR templates
• [ ] Active FHIR discussion in forums
• [ ] 100+ GitHub stars/forks for FHIR templates
• [ ] 10+ blog posts by users about FHIR usage
• [ ] Community maintains FHIR template library

9. Next Steps

Immediate Actions (This Week)

1. Stakeholder Approval

Action: Review this analysis with product team and stakeholders

Questions to Answer:

• [ ] Do we agree with phased approach?
• [ ] Is 16-week timeline acceptable?
• [ ] Do we have resources (1 FTE developer)?
• [ ] Which tier is highest priority?
• [ ] Any additional requirements?

Deliverable: Signed-off implementation plan

2. Set Up FHIR Project

Action: Create @FHIR project in SDCStudio

Steps:

1. Log into SDCStudio as admin
2. Navigate to Projects → Create New Project
3. Fill in details:

```

Name: FHIR

Label: FHIR

Description: Fast Healthcare Interoperability Resources (HL7 FHIR R4)

Version: R4 (4.0.1)

Creator: SDCStudio Team

Published: true

Public: true

About: http://hl7.org/fhir/

```

1. Add metadata:

```

dc_subject: Healthcare Interoperability, FHIR, HL7, Semantic Data

dc_source: https://www.hl7.org/fhir/datatypes.html

dc_rights: Content derived from HL7 FHIR specification (CC BY 4.0)

dc_publisher: HL7 International

dc_type: SDC Component Library

```

1. Save and verify project created

Deliverable: Active @FHIR project ready for components

3. Create First Template (Identifier)

Action: Build and publish Identifier component

Steps:

1. Create file: docs/templates/fhir/datatypes/fhir-identifier.md
2. Use template structure from Section 3.2
3. Add YAML front matter:

```yaml

template_version: "4.0.0"

dataset:

name: "FHIR Identifier"

description: "Business identifier with namespace and validity period (FHIR R4)"

project: "@FHIR"

creator: "SDCStudio Team"

enrichment:

enable_llm: false

```

1. Upload to SDCStudio
2. Verify parsing successful
3. Publish component
4. Test reuse with ReuseComponent: @FHIR:Identifier

Deliverable: Published @FHIR:Identifier component

4. Update Documentation

Action: Add FHIR section to SDCStudio documentation

Files to Create/Update:

1. docs/FHIR/FHIRDATATYPESANALYSIS.md (this document)
2. docs/templates/fhir/README.md (template catalog index)
3. docs/templates/README.md (add FHIR section)
4. docs/users/fhir-integration-guide.md (user guide - start draft)

Content for docs/templates/README.md:

## FHIR Templates

HL7 FHIR (Fast Healthcare Interoperability Resources) R4 datatypes and resources.

**Location**: `fhir/`

**Usage**:

ReuseComponent: @FHIR:Identifier

ReuseComponent: @FHIR:HumanName

ReuseComponent: @FHIR:Address

**Documentation**: See [FHIR Integration Guide](../users/fhir-integration-guide.md)

**Reference**: https://www.hl7.org/fhir/datatypes.html

Deliverable: FHIR documentation integrated into SDCStudio docs

Week 1 Goals

By End of Week 1:

• [x] FHIR analysis document saved to docs/FHIR/
• [ ] @FHIR project created and configured
• [ ] Identifier component published
• [ ] HumanName component published
• [ ] Address component published
• [ ] Example Patient demographics model started
• [ ] Initial documentation published
• [ ] Development environment set up
• [ ] Team briefed on implementation plan

Success Criteria:

• At least 3 FHIR components published and tested
• Component reuse validated (@FHIR:ComponentName syntax working)
• No blockers for Week 2 work
• Team confident in plan

10. Resource Requirements

10.1 Development Resources

Personnel:

• 1 FTE Developer with:
  • FHIR specification expertise (HL7 FHIR R4)
  • Healthcare data modeling experience
  • SDCStudio architecture familiarity
  • XML Schema and validation knowledge
  • Django/Python proficiency
  • Technical writing skills

Time Allocation:

• Phase 1 (Weeks 1-4): 4 weeks
• Phase 2 (Weeks 5-8): 4 weeks
• Phase 3 (Weeks 9-12): 4 weeks
• Phase 4 (Weeks 13-16): 4 weeks
• Total: 16 weeks (4 months)

Effort Distribution:

• Component development: 60%
• Template creation: 15%
• Testing and validation: 15%
• Documentation: 10%

10.2 Knowledge Resources

Required Expertise:

1. FHIR Specification:
   • FHIR R4 Datatypes: https://www.hl7.org/fhir/datatypes.html
   • FHIR Resources: https://www.hl7.org/fhir/resourcelist.html
   • FHIR Profiles: https://www.hl7.org/fhir/profiling.html
   • US Core: http://hl7.org/fhir/us/core/
2. Healthcare Standards:
   • SNOMED CT terminology
   • LOINC codes
   • ICD-10 diagnosis codes
   • UCUM units
   • HL7 v2/v3 (for context)
3. SDCStudio Architecture:
   • SDC4 reference model
   • Component types (XdString, XdQuantity, etc.)
   • Cluster hierarchy
   • Template parsing system
   • XSD generation
4. Development Tools:
   • Django ORM and models
   • Celery task processing
   • PostgreSQL
   • Git version control
   • Markdown/YAML

10.3 Testing Resources

Test Data:

• FHIR sample data sets (from HL7)
• Synthea synthetic patient data
• FHIR example instances (from spec)
• Real-world de-identified data (if available)

Validation Tools:

• FHIR Validator (official HL7 tool)
• HAPI FHIR server (for validation)
• XMLSpy or similar for XSD validation
• JSON-LD validator
• RDF triple validator

Testing Environment:

• Development SDCStudio instance
• Staging SDCStudio instance
• FHIR test server (HAPI FHIR or similar)
• CI/CD pipeline for automated testing

10.4 Infrastructure Resources

Development:

• Git repository (existing)
• Development database (existing)
• Celery worker (existing)
• Local Obsidian vault for template testing

Documentation:

• Markdown editor
• Screenshot tools
• Video recording for tutorials
• Diagram tools (for architecture)

External Services:

• FHIR terminology server (for ValueSet lookups)
• UCUM validation service
• Ontology lookup services (optional)

10.5 Budget Considerations

Personnel Costs:

• 1 FTE developer × 4 months
• Technical writer support (part-time)
• Healthcare SME review (consultancy)
• QA/testing support

Software/Services:

• FHIR validation tools (mostly free)
• Terminology services (may have costs)
• Training/conference attendance
• Documentation tools

Estimated Total:

• Personnel: Majority of budget
• Software/Services: Minimal (most FHIR tools are open source)
• Training: Small allocation for FHIR certification
• ROI Expected: 6-12 months based on healthcare market opportunity

Conclusion

This comprehensive analysis demonstrates that FHIR integration is highly feasible and represents a significant strategic opportunity for SDCStudio to establish itself as the premier healthcare data modeling tool.

Key Strengths

Technical Fit:

• ✅ SDC4 component types align well with FHIR primitives (90% direct mapping)
• ✅ Cluster system is ideal for FHIR complex datatypes
• ✅ Component reuse architecture (@FHIR:ComponentName) is intuitive and powerful
• ✅ MD2PD template system makes FHIR accessible to non-technical users
• ✅ Existing infrastructure (XSD generation, RDF, validation) supports FHIR

Market Opportunity:

• 🎯 Healthcare is a massive market with mandated FHIR adoption
• 🎯 Current tools are complex and developer-focused
• 🎯 SDCStudio can democratize FHIR modeling for clinical users
• 🎯 Reusable component library reduces modeling time by 50%+
• 🎯 Standards-based approach ensures long-term viability

Manageable Scope:

• ✅ Tier 1 (7 components) enables 80% of use cases in 4 weeks
• ✅ Phased approach allows incremental value delivery
• ✅ Clear success criteria and metrics
• ✅ Reasonable resource requirements (1 FTE × 4 months)
• ✅ Low technical risk with current architecture

Key Challenges

Complexity Areas:

• ⚠️ Repeating elements (arrays) - Manageable with multi-row approach (Option A)
• ⚠️ Choice types (value[x]) - Addressable with union clusters
• ⚠️ Dosage and Timing datatypes - Very complex but documented in spec
• ⚠️ Terminology binding - Requires enumeration management

None of these challenges are blockers - all have documented solutions.

Strategic Recommendation

PROCEED with FHIR integration using the phased approach outlined in this document.

Start immediately with:

1. Create @FHIR project
2. Implement Tier 1 (7 critical components) in 4 weeks
3. Build example Patient demographics model
4. Document and socialize success

This positions SDCStudio as:

• The easiest way to create FHIR-compliant data models
• A bridge between clinical users and FHIR complexity
• A standards-based, future-proof healthcare data platform

Expected ROI:

• Initial investment: 1 FTE × 4 months (Phase 1-2)
• Payback: 6-12 months through healthcare market expansion
• Long-term value: Established position in growing healthcare IT market

Final Assessment: ⭐⭐⭐⭐⭐ HIGHLY RECOMMENDED

The technical fit is excellent, the market opportunity is substantial, the risks are manageable, and the phased approach allows for learning and adjustment. This is a high-value, achievable initiative that aligns perfectly with SDCStudio's strengths and vision.

Appendices

Appendix A: FHIR Resources by Category

Foundation Module (11 resources):

• Patient, Practitioner, Person, RelatedPerson
• Organization, Location, Endpoint
• HealthcareService, Device, Substance
• Group

Clinical Module (19 resources):

• Observation, Condition, Procedure, MedicationRequest
• AllergyIntolerance, Immunization, CarePlan, Goal
• ClinicalImpression, DetectedIssue, RiskAssessment
• FamilyMemberHistory, AdverseEvent, CareTeam
• Communication, DocumentReference, Consent
• DeviceUseStatement, VisionPrescription

Diagnostics Module (6 resources):

• DiagnosticReport, Observation (reused)
• ImagingStudy, Media, Specimen
• BodyStructure

Medications Module (5 resources):

• Medication, MedicationRequest, MedicationDispense
• MedicationAdministration, MedicationStatement

Workflow Module (11 resources):

• Appointment, AppointmentResponse, Schedule
• Slot, Task, ServiceRequest
• NutritionOrder, VisionPrescription
• RiskAssessment, RequestGroup, PlanDefinition

Financial Module (15 resources):

• Coverage, EligibilityRequest, EligibilityResponse
• Claim, ClaimResponse, Account
• ChargeItem, ChargeItemDefinition, Contract
• PaymentNotice, PaymentReconciliation, ExplanationOfBenefit
• InsurancePlan, CoverageEligibilityRequest, CoverageEligibilityResponse

Appendix B: FHIR Terminology Systems

Common Code Systems:

• SNOMED CT: http://snomed.info/sct (clinical terminology)
• LOINC: http://loinc.org (lab and clinical observations)
• RxNorm: http://www.nlm.nih.gov/research/umls/rxnorm (medications)
• ICD-10: http://hl7.org/fhir/sid/icd-10 (diagnoses)
• CPT: http://www.ama-assn.org/go/cpt (procedures)
• UCUM: http://unitsofmeasure.org (units of measure)
• HL7 v2/v3: http://terminology.hl7.org (HL7 codes)
• FHIR: http://hl7.org/fhir (FHIR-specific codes)

Usage in SDCStudio:

• Use in Semantic Links for terminology mappings
• Reference in system field of Coding
• Document in template examples

Appendix C: Useful FHIR Resources

Official Resources:

• FHIR R4 Specification: https://www.hl7.org/fhir/
• FHIR Datatypes: https://www.hl7.org/fhir/datatypes.html
• FHIR Resources: https://www.hl7.org/fhir/resourcelist.html
• US Core: http://hl7.org/fhir/us/core/
• FHIR Chat: https://chat.fhir.org/

Tools:

• FHIR Validator: https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator
• HAPI FHIR: https://hapifhir.io/
• Synthea: https://github.com/synthetichealth/synthea (synthetic data)
• FHIR Playground: https://fhir.epic.com/Sandbox

Learning:

• HL7 FHIR Education: https://www.hl7.org/fhir/overview.html
• FHIR Proficiency: https://www.fhirproficiency.org/
• FHIR DevDays: https://www.devdays.com/

Appendix D: Version History

End of Document

This analysis provides the foundation for FHIR integration with SDC4. Implementation should follow the phased roadmap with continuous feedback and adjustment.

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 ABOUTSDC4ANDSDCSTUDIO.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)