0
# FHIR Resources
1

2
A comprehensive Python library providing classes for all FHIR (Fast Healthcare Interoperability Resources) resources across multiple specification versions. Built on Pydantic for high-performance data validation and serialization, this library enables developers to create, manipulate, and validate FHIR resources programmatically with full compliance to healthcare interoperability standards.
3

4
## Package Information
5

6
- **Package Name**: fhir.resources
7
- **Language**: Python
8
- **Installation**: `pip install fhir.resources`
9

10
## Core Imports
11

12
```python
13
import fhir.resources
14
from fhir.resources import get_fhir_model_class, construct_fhir_element
15
```
16

17
For specific FHIR resources (R5 - default version):
18

19
```python
20
from fhir.resources.patient import Patient
21
from fhir.resources.observation import Observation
22
from fhir.resources.bundle import Bundle
23
```
24

25
**Import Notes**: The main `fhir.resources` package only exports the core functions `get_fhir_model_class` and `construct_fhir_element`. Individual FHIR resources must be imported from their specific modules (e.g., `from fhir.resources.patient import Patient`) or accessed dynamically using `get_fhir_model_class("Patient")`.
26

27
For version-specific resources:
28

29
```python
30
# R4B
31
from fhir.resources.R4B import Patient as PatientR4B
32

33
# STU3  
34
from fhir.resources.STU3 import Patient as PatientSTU3
35

36
# DSTU2
37
from fhir.resources.DSTU2 import Patient as PatientDSTU2
38
```
39

40
## Basic Usage
41

42
```python
43
from fhir.resources.patient import Patient
44
from fhir.resources.humanname import HumanName
45
from fhir.resources.identifier import Identifier
46
from fhir.resources import get_fhir_model_class, construct_fhir_element
47

48
# Create a patient with demographic information
49
patient = Patient(
50
    id="patient-123",
51
    active=True,
52
    name=[
53
        HumanName(
54
            use="official",
55
            family="Doe",
56
            given=["John", "F"]
57
        )
58
    ],
59
    identifier=[
60
        Identifier(
61
            use="usual",
62
            system="urn:oid:1.2.36.146.595.217.0.1",
63
            value="12345"
64
        )
65
    ]
66
)
67

68
# Serialize to JSON
69
patient_json = patient.json()
70
print(patient_json)
71

72
# Parse from JSON string
73
patient_data = '{"resourceType": "Patient", "id": "123", "active": true}'
74
patient_from_json = Patient.parse_raw(patient_data)
75

76
# Dynamic resource creation
77
PatientClass = get_fhir_model_class("Patient")
78
patient_dynamic = PatientClass.parse_obj({"resourceType": "Patient", "active": True})
79

80
# Construct from various data formats
81
patient_from_dict = construct_fhir_element("Patient", {"active": True})
82
patient_from_file = construct_fhir_element("Patient", "patient.json")
83
```
84

85
## Architecture
86

87
FHIR resources follow a hierarchical structure based on the FHIR specification:
88

89
- **Base**: Foundation class for all FHIR elements with essential properties
90
- **Resource**: Base class for all FHIR resources with meta, implicitRules, and language
91
- **DomainResource**: Base for clinical resources adding text, contained, extension, and modifierExtension
92
- **Specialized Resources**: Patient, Observation, Encounter, etc. - specific clinical and administrative resources
93

94
The library supports multiple FHIR versions (R5, R4B, STU3, DSTU2) with version-specific modules, each containing the complete set of resources and data types defined in that FHIR specification version.
95

96
## Capabilities
97

98
### Core Functions
99

100
Essential utilities for dynamic FHIR resource creation and manipulation, enabling flexible resource handling without hardcoded resource types.
101

102
```python { .api }
103
def get_fhir_model_class(model_name: str) -> Type[FHIRAbstractModel]:
104
    """Get FHIR model class by resource/element name."""
105

106
def construct_fhir_element(
107
    element_type: str, 
108
    data: Union[Dict[str, Any], str, bytes, Path]
109
) -> FHIRAbstractModel:
110
    """Construct FHIR element from various data formats."""
111
```
112

113
[Core Functions](./core-functions.md)
114

115
### FHIR Data Types
116

117
Comprehensive set of FHIR primitive and complex data types including strings, dates, quantities, addresses, and coded concepts with full validation.
118

119
```python { .api }
120
# Primitive types
121
class Boolean: ...
122
class String: ...
123
class DateTime: ...
124
class Decimal: ...
125
class Integer: ...
126

127
# Complex types  
128
class HumanName: ...
129
class Address: ...
130
class CodeableConcept: ...
131
class Identifier: ...
132
class Quantity: ...
133
```
134

135
[Data Types](./data-types.md)
136

137
### Patient Resources
138

139
Comprehensive patient demographics and identity management including names, addresses, contacts, communication preferences, and relationships.
140

141
```python { .api }
142
class Patient(DomainResource):
143
    def __init__(
144
        self,
145
        active: Optional[bool] = None,
146
        name: Optional[List[HumanName]] = None,
147
        identifier: Optional[List[Identifier]] = None,
148
        gender: Optional[str] = None,
149
        birthDate: Optional[str] = None,
150
        address: Optional[List[Address]] = None,
151
        **kwargs
152
    ): ...
153
```
154

155
[Patient Resources](./patient-resources.md)
156

157
### Clinical Resources
158

159
Clinical data including observations, conditions, procedures, medications, and diagnostic reports for comprehensive healthcare documentation.
160

161
```python { .api }
162
class Observation(DomainResource): ...
163
class Condition(DomainResource): ...
164
class Procedure(DomainResource): ...
165
class MedicationRequest(DomainResource): ...
166
class DiagnosticReport(DomainResource): ...
167
```
168

169
[Clinical Resources](./clinical-resources.md)
170

171
### Administrative Resources
172

173
Healthcare administration including appointments, encounters, organizations, practitioners, and schedules for operational management.
174

175
```python { .api }
176
class Appointment(DomainResource): ...
177
class Encounter(DomainResource): ...
178
class Organization(DomainResource): ...
179
class Practitioner(DomainResource): ...
180
class Schedule(DomainResource): ...
181
```
182

183
[Administrative Resources](./administrative-resources.md)
184

185
### Financial Resources
186

187
Healthcare financial transactions including claims, coverage, payments, and billing for insurance and payment processing.
188

189
```python { .api }
190
class Claim(DomainResource): ...
191
class Coverage(DomainResource): ...
192
class ExplanationOfBenefit(DomainResource): ...
193
class PaymentReconciliation(DomainResource): ...
194
```
195

196
[Financial Resources](./financial-resources.md)
197

198
### Serialization
199

200
Multi-format serialization supporting JSON, XML, and YAML with flexible parsing from strings, bytes, or files.
201

202
```python { .api }
203
# Instance methods available on all FHIR resources
204
def json(self, **kwargs) -> str: ...
205
def xml(self, **kwargs) -> str: ...
206
def yaml(self, **kwargs) -> str: ...
207
def dict(self, **kwargs) -> Dict[str, Any]: ...
208

209
# Class methods for parsing
210
@classmethod
211
def parse_raw(cls, data: Union[str, bytes], content_type: str = None): ...
212

213
@classmethod  
214
def parse_file(cls, path: Union[str, Path]): ...
215

216
@classmethod
217
def parse_obj(cls, data: Dict[str, Any]): ...
218
```
219

220
[Serialization](./serialization.md)
221

222
### Version Support
223

224
Multi-version FHIR support with dedicated modules for R5, R4B, STU3, and DSTU2, each containing version-appropriate resources and validation.
225

226
```python { .api }
227
# Version-specific imports
228
from fhir.resources.R4B import Patient as PatientR4B
229
from fhir.resources.STU3 import Patient as PatientSTU3  
230
from fhir.resources.DSTU2 import Patient as PatientDSTU2
231
```
232

233
[Version Support](./version-support.md)