Skip to content
Scribe2FHIR Documentation

scribe2fhir FHIR Specification Documentation

This directory contains comprehensive FHIR specification documentation for the scribe2fhir SDK, ensuring consistent output across all programming language implementations.

Documentation Structure

Section titled “Documentation Structure”

Core Specification Documents

Section titled “Core Specification Documents”

Purpose

Section titled “Purpose”

This specification ensures that all scribe2fhir SDK implementations (Python, JavaScript, Java, C#, etc.) produce identical FHIR Bundle output for identical input, maintaining interoperability across different programming languages and healthcare systems.

Key Principles

Section titled “Key Principles”

1. Output Consistency

Section titled “1. Output Consistency”

All language SDKs MUST generate identical FHIR Bundles:

  • Same resource structures and field names
  • Same default values and behaviors
  • Same reference patterns and relationships
  • Same validation rules and constraints

2. Input Flexibility

Section titled “2. Input Flexibility”

While output is standardized, input methods should be language-appropriate:

  • Native datetime objects
  • Language-specific string formats
  • Idiomatic parameter patterns
  • Framework-specific integrations

3. FHIR Compliance

Section titled “3. FHIR Compliance”

All SDKs MUST produce FHIR R5 compliant output:

  • Valid resource structures
  • Proper coding systems usage
  • Correct reference formats
  • Required field population

Implementation Requirements

Section titled “Implementation Requirements”

Supported Elements (20 Total)

Section titled “Supported Elements (20 Total)”

Each SDK MUST implement all element types:

Core Elements (2):

  • Patient - Demographics and identifiers
  • Encounter - Healthcare interaction context

Clinical Observations (5):

  • Symptom - Patient-reported symptoms
  • Vital Signs - Physiological measurements
  • Lab Findings - Laboratory test results
  • Examination Findings - Physical exam results
  • Lifestyle History - Social history factors

Medical Conditions (2):

  • Medical Condition History - Problem list conditions
  • Medical Condition Encountered - Current visit diagnoses

Medications (2):

  • Medication Prescription - Active prescriptions
  • Medication History - Current/past medication usage

Service Requests (2):

  • Lab Test Ordering - Laboratory test orders
  • Procedure Ordering - Procedure/imaging orders

Historical Information (4):

  • Family History - Family medical conditions
  • Allergy History - Allergies and adverse reactions
  • Immunization History - Vaccination records
  • Procedure History - Past surgical procedures

Care Coordination (3):

  • Follow-up Appointment - Scheduled appointments
  • Patient Advice - Care instructions
  • Clinical Notes - Provider documentation

Method Requirements

Section titled “Method Requirements”

Each element MUST be implemented as a method on the DocumentBuilder with the signature specified in the implementation guide.

Bundle Generation

Section titled “Bundle Generation”

The convertToFHIR() method MUST:

  • Return valid FHIR R5 Bundle JSON
  • Include all added resources in proper order
  • Generate correct metadata and references
  • Follow exact structure requirements

Validation Strategy

Section titled “Validation Strategy”

Cross-Language Testing

Section titled “Cross-Language Testing”
  1. Golden Standard Tests: Use Python SDK output as reference
  2. Identical Input Testing: Same input parameters across languages
  3. JSON Comparison: Field-by-field bundle comparison
  4. Schema Validation: Validate against FHIR R5 schemas

Compliance Checklist

Section titled “Compliance Checklist”
  • All 20 element methods implemented
  • Bundle structure matches specification
  • Resource ordering follows requirements
  • Reference management works correctly
  • Default values match specification
  • Category codes are exact matches
  • DateTime formatting is consistent
  • UUID generation follows v4 standard
  • Error handling is appropriate
  • Documentation is complete

Development Process

Section titled “Development Process”

1. Setup Phase

Section titled “1. Setup Phase”
  • Create project structure
  • Set up FHIR library dependencies
  • Implement base DocumentBuilder class
  • Create helper functions and utilities

2. Core Elements Phase

Section titled “2. Core Elements Phase”
  • Implement Patient and Encounter elements
  • Establish reference management patterns
  • Create basic bundle generation
  • Write initial tests

3. Observation Elements Phase

Section titled “3. Observation Elements Phase”
  • Implement all 5 observation types
  • Ensure category differentiation
  • Handle component structures correctly
  • Test value handling (numeric vs string)

4. Complex Elements Phase

Section titled “4. Complex Elements Phase”
  • Implement conditions, medications, service requests
  • Handle complex nested structures (dosage, dispense request)
  • Implement historical information elements
  • Test cross-resource references

5. Care Coordination Phase

Section titled “5. Care Coordination Phase”
  • Implement appointments, advice, and notes
  • Handle participant and activity structures
  • Complete reference relationships
  • Finalize bundle generation

6. Testing and Validation Phase

Section titled “6. Testing and Validation Phase”
  • Create comprehensive test suite
  • Implement compatibility testing
  • Validate against Python reference
  • Performance and stress testing

7. Documentation Phase

Section titled “7. Documentation Phase”
  • Create API documentation
  • Adapt element documentation for language
  • Write integration examples
  • Create troubleshooting guides

Quality Gates

Section titled “Quality Gates”

Before Release

Section titled “Before Release”

Each language SDK MUST pass:

  1. Unit Tests: 90%+ test coverage
  2. Integration Tests: All element combinations work
  3. Compatibility Tests: Output matches Python SDK
  4. Schema Validation: All output validates against FHIR R5
  5. Performance Tests: Bundle generation meets requirements
  6. Documentation Review: Complete and accurate documentation

Continuous Validation

Section titled “Continuous Validation”
  • Automated testing against reference implementation
  • FHIR schema validation in CI/CD
  • Cross-language compatibility monitoring
  • Performance regression testing

Support and Maintenance

Section titled “Support and Maintenance”

Issue Tracking

Section titled “Issue Tracking”
  • Language-specific issues in respective repositories
  • Cross-language specification issues in main repository
  • Breaking change coordination across implementations

Documentation Maintenance

Section titled “Documentation Maintenance”
  • Keep specification updated as requirements evolve
  • Synchronize element documentation across languages
  • Update examples and best practices
  • Maintain troubleshooting guides

Reference Implementation

Section titled “Reference Implementation”

The Python SDK serves as the reference implementation:

  • Location: /python/scribe2fhir/core/
  • Tests: /python/tests/ (165+ test methods)
  • Documentation: /python/docs/ (20+ documentation files)
  • Examples: /python/example_usage.py

Use Python implementation for:

  • Understanding expected behavior
  • Validating output format
  • Testing compatibility
  • Reference documentation patterns

Getting Started

Section titled “Getting Started”

To implement a new language SDK:

  1. Review this specification thoroughly
  2. Study the Python reference implementation
  3. Set up project structure following the pattern
  4. Begin with Phase 1 (Core Infrastructure)
  5. Implement incrementally with testing at each phase
  6. Validate output compatibility continuously

The goal is identical FHIR output regardless of programming language, ensuring seamless interoperability across the scribe2fhir ecosystem.