0
# Version Support
1

2
Multi-version FHIR support with dedicated modules for R5, R4B, STU3, and DSTU2, each containing version-appropriate resources and validation. This enables applications to work with different FHIR specification versions based on implementation requirements.
3

4
## Capabilities
5

6
### FHIR Version Overview
7

8
Support for multiple FHIR specification versions with complete resource sets and validation for each version.
9

10
```python { .api }
11
# Default version (R5)
12
from fhir.resources.patient import Patient  # R5 version
13

14
# Version-specific imports
15
from fhir.resources.R4B import Patient as PatientR4B
16
from fhir.resources.STU3 import Patient as PatientSTU3
17
from fhir.resources.DSTU2 import Patient as PatientDSTU2
18

19
# Version information
20
__version__ = "7.1.0"  # Package version
21
__fhir_version__ = "5.0.0"  # Default FHIR version (R5)
22
```
23

24
### R5 Support (Default)
25

26
FHIR R5 (5.0.0) - Latest FHIR specification with the most comprehensive resource set and advanced features.
27

28
```python { .api }
29
# R5 is the default version
30
from fhir.resources.patient import Patient
31
from fhir.resources.observation import Observation
32
from fhir.resources.bundle import Bundle
33

34
# Core R5 features
35
# Administrative resources
36
from fhir.resources.account import Account
37
from fhir.resources.activitydefinition import ActivityDefinition
38
from fhir.resources.actordefinition import ActorDefinition
39
from fhir.resources.administrableproductdefinition import AdministrableProductDefinition
40
from fhir.resources.appointment import Appointment
41
from fhir.resources.appointmentresponse import AppointmentResponse
42
from fhir.resources.auditevent import AuditEvent
43
from fhir.resources.basic import Basic
44
from fhir.resources.binary import Binary
45
from fhir.resources.bundle import Bundle
46
from fhir.resources.capabilitystatement import CapabilityStatement
47
from fhir.resources.chargeitem import ChargeItem
48
from fhir.resources.chargeitemdefinition import ChargeItemDefinition
49
from fhir.resources.citation import Citation
50

51
# Clinical resources
52
from fhir.resources.allergyintolerance import AllergyIntolerance
53
from fhir.resources.bodystructure import BodyStructure
54
from fhir.resources.careplan import CarePlan
55
from fhir.resources.careteam import CareTeam
56
from fhir.resources.clinicalimpression import ClinicalImpression
57
from fhir.resources.communication import Communication
58
from fhir.resources.communicationrequest import CommunicationRequest
59
from fhir.resources.condition import Condition
60
from fhir.resources.diagnosticreport import DiagnosticReport
61
from fhir.resources.encounter import Encounter
62
from fhir.resources.familymemberhistory import FamilyMemberHistory
63
from fhir.resources.goal import Goal
64
from fhir.resources.imagingstudy import ImagingStudy
65
from fhir.resources.immunization import Immunization
66

67
# Medication resources
68
from fhir.resources.medication import Medication
69
from fhir.resources.medicationadministration import MedicationAdministration
70
from fhir.resources.medicationdispense import MedicationDispense
71
from fhir.resources.medicationknowledge import MedicationKnowledge
72
from fhir.resources.medicationrequest import MedicationRequest
73
from fhir.resources.medicationstatement import MedicationStatement
74

75
# Financial resources
76
from fhir.resources.claim import Claim
77
from fhir.resources.claimresponse import ClaimResponse
78
from fhir.resources.coverage import Coverage
79
from fhir.resources.explanationofbenefit import ExplanationOfBenefit
80

81
# And 150+ other resources...
82

83
# R5 version identifier
84
from fhir.resources import __fhir_version__
85
print(__fhir_version__)  # "5.0.0"
86
```
87

88
**R5 Features:**
89
- 150+ resource types
90
- Advanced search parameters
91
- Enhanced terminology support
92
- Improved extension mechanisms
93
- Latest data types and constraints
94

95
### R4B Support
96

97
FHIR R4B (4.3.0) - Intermediate version between R4 and R5 with selected R5 features backported to R4.
98

99
```python { .api }
100
# R4B version-specific imports
101
from fhir.resources.R4B import (
102
    Patient, Observation, Encounter, Condition,
103
    MedicationRequest, DiagnosticReport, Bundle
104
)
105

106
# R4B core functions
107
from fhir.resources.R4B import get_fhir_model_class, construct_fhir_element
108

109
# Version information
110
from fhir.resources.R4B import __fhir_version__
111
print(__fhir_version__)  # "4.3.0"
112
```
113

114
**Usage Example:**
115

116
```python
117
from fhir.resources.R4B import Patient, HumanName, Identifier
118

119
# Create R4B patient
120
patient_r4b = Patient(
121
    id="patient-r4b-001",
122
    active=True,
123
    name=[
124
        HumanName(
125
            use="official",
126
            family="Johnson",
127
            given=["Michael"]
128
        )
129
    ],
130
    identifier=[
131
        Identifier(
132
            use="usual",
133
            system="http://hospital.example.org/patients",
134
            value="R4B-123456"
135
        )
136
    ]
137
)
138

139
# R4B-specific features
140
json_output = patient_r4b.json()
141
```
142

143
### STU3 Support
144

145
FHIR STU3 (3.0.2) - Standard for Trial Use 3, widely adopted version with mature resource definitions.
146

147
```python { .api }
148
# STU3 version-specific imports
149
from fhir.resources.STU3 import (
150
    Patient, Observation, Encounter, Condition,
151
    MedicationRequest, DiagnosticReport, Bundle
152
)
153

154
# STU3 core functions
155
from fhir.resources.STU3 import get_fhir_model_class, construct_fhir_element
156

157
# Version information
158
from fhir.resources.STU3 import __fhir_version__
159
print(__fhir_version__)  # "3.0.2"
160
```
161

162
**Usage Example:**
163

164
```python
165
from fhir.resources.STU3 import Patient, HumanName
166

167
# Create STU3 patient
168
patient_stu3 = Patient(
169
    id="patient-stu3-001",
170
    active=True,
171
    name=[
172
        HumanName(
173
            use="official",
174
            family="Williams",
175
            given=["Sarah"]
176
        )
177
    ]
178
)
179

180
# STU3-specific validation and serialization
181
xml_output = patient_stu3.xml(pretty=True)
182
```
183

184
**STU3 Characteristics:**
185
- ~100 resource types
186
- Mature and stable specification
187
- Wide industry adoption
188
- Good balance of features and simplicity
189

190
### DSTU2 Support
191

192
FHIR DSTU2 (1.0.2) - Draft Standard for Trial Use 2, legacy version for backward compatibility.
193

194
```python { .api }
195
# DSTU2 version-specific imports
196
from fhir.resources.DSTU2 import (
197
    Patient, Observation, Encounter, Condition,
198
    MedicationOrder, DiagnosticReport, Bundle
199
)
200

201
# DSTU2 core functions
202
from fhir.resources.DSTU2 import get_fhir_model_class, construct_fhir_element
203

204
# Version information
205
from fhir.resources.DSTU2 import __fhir_version__
206
print(__fhir_version__)  # "1.0.2"
207
```
208

209
**Usage Example:**
210

211
```python
212
from fhir.resources.DSTU2 import Patient, HumanName
213

214
# Create DSTU2 patient
215
patient_dstu2 = Patient(
216
    id="patient-dstu2-001",
217
    active=True,
218
    name=[
219
        HumanName(
220
            use="official",
221
            family=["Brown"],  # Note: DSTU2 uses array for family name
222
            given=["David"]
223
        )
224
    ]
225
)
226

227
# DSTU2-specific serialization
228
json_output = patient_dstu2.json()
229
```
230

231
**DSTU2 Characteristics:**
232
- ~80 resource types
233
- Legacy specification
234
- Different resource structures
235
- Limited compared to newer versions
236

237
### Version Migration
238

239
Utilities and patterns for migrating resources between FHIR versions.
240

241
```python { .api }
242
def migrate_resource(
243
    resource: FHIRAbstractModel, 
244
    target_version: str
245
) -> FHIRAbstractModel:
246
    """
247
    Migrate FHIR resource between versions.
248
    
249
    Parameters:
250
    - resource: Source FHIR resource
251
    - target_version: Target FHIR version ('R5', 'R4B', 'STU3', 'DSTU2')
252
    
253
    Returns:
254
    FHIRAbstractModel - Migrated resource in target version
255
    
256
    Note: This is a conceptual function - actual migration
257
    requires manual handling of version differences
258
    """
259
```
260

261
**Migration Examples:**
262

263
```python
264
from fhir.resources.patient import Patient as PatientR5
265
from fhir.resources.STU3 import Patient as PatientSTU3
266

267
# Manual migration from R5 to STU3
268
patient_r5 = PatientR5(
269
    id="patient-001",
270
    active=True,
271
    name=[HumanName(family="Smith", given=["John"])]
272
)
273

274
# Convert via dictionary (handles common fields)
275
patient_dict = patient_r5.dict()
276

277
# Create STU3 version (may need field adjustments)
278
try:
279
    patient_stu3 = PatientSTU3.parse_obj(patient_dict)
280
except ValidationError as e:
281
    # Handle version-specific differences
282
    print(f"Migration requires manual field mapping: {e}")
283
```
284

285
### Version Comparison
286

287
Key differences between FHIR versions to guide version selection.
288

289
```python { .api }
290
# Version feature comparison
291
VERSION_FEATURES = {
292
    "R5": {
293
        "resources": 150+,
294
        "status": "Current",
295
        "features": ["Advanced search", "Enhanced terminology", "New data types"],
296
        "use_case": "New implementations, future-proofing"
297
    },
298
    "R4B": {
299
        "resources": 140+,
300
        "status": "Maintenance",
301
        "features": ["Selected R5 features", "R4 compatibility"],
302
        "use_case": "R4 implementations needing specific R5 features"
303
    },
304
    "STU3": {
305
        "resources": 100+,
306
        "status": "Mature",
307
        "features": ["Stable specification", "Wide adoption"],
308
        "use_case": "Production systems, EHR integration"
309
    },
310
    "DSTU2": {
311
        "resources": 80,
312
        "status": "Legacy",
313
        "features": ["Basic FHIR functionality"],
314
        "use_case": "Legacy system support only"
315
    }
316
}
317
```
318

319
### Dynamic Version Selection
320

321
Runtime version selection based on application requirements.
322

323
```python { .api }
324
def get_version_module(version: str):
325
    """
326
    Get FHIR version module dynamically.
327
    
328
    Parameters:
329
    - version: str - FHIR version ('R5', 'R4B', 'STU3', 'DSTU2')
330
    
331
    Returns:
332
    Module - FHIR version module
333
    """
334
    
335
def get_resource_class(resource_name: str, version: str = "R5"):
336
    """
337
    Get resource class from specific FHIR version.
338
    
339
    Parameters:
340
    - resource_name: str - FHIR resource name
341
    - version: str - FHIR version (default: R5)
342
    
343
    Returns:
344
    Type[FHIRAbstractModel] - Resource class from specified version
345
    """
346
```
347

348
**Usage Example:**
349

350
```python
351
# Dynamic version selection
352
def create_patient(version="R5", **kwargs):
353
    if version == "R5":
354
        from fhir.resources.patient import Patient
355
    elif version == "R4B":
356
        from fhir.resources.R4B import Patient
357
    elif version == "STU3":
358
        from fhir.resources.STU3 import Patient
359
    elif version == "DSTU2":
360
        from fhir.resources.DSTU2 import Patient
361
    else:
362
        raise ValueError(f"Unsupported version: {version}")
363
    
364
    return Patient(**kwargs)
365

366
# Create patients for different versions
367
patient_r5 = create_patient("R5", active=True)
368
patient_stu3 = create_patient("STU3", active=True)
369
```
370

371
## Types
372

373
```python { .api }
374
from typing import Literal, Union
375
from fhir.resources.core.fhirabstractmodel import FHIRAbstractModel
376

377
# Version identifiers
378
FHIRVersion = Literal["R5", "R4B", "STU3", "DSTU2"]
379

380
# Version-specific resource types
381
R5Resource = Union[
382
    "Patient", "Observation", "Encounter", "Condition",
383
    # ... all R5 resources
384
]
385

386
R4BResource = Union[
387
    "Patient", "Observation", "Encounter", "Condition", 
388
    # ... all R4B resources
389
]
390

391
STU3Resource = Union[
392
    "Patient", "Observation", "Encounter", "Condition",
393
    # ... all STU3 resources  
394
]
395

396
DSTU2Resource = Union[
397
    "Patient", "Observation", "Encounter", "Condition",
398
    # ... all DSTU2 resources
399
]
400

401
# Migration result
402
class MigrationResult:
403
    success: bool
404
    target_resource: FHIRAbstractModel
405
    warnings: List[str]
406
    errors: List[str]
407
```