FHIR supports multiple serialization formats. Understanding when each applies avoids format confusion in integrations.
JSON (default)
- Content-Type: application/fhir+json - Use for: individual resource CRUD, Bundle transactions, standard REST responses. - Serialization: canonical JSON per FHIR spec.
NDJSON (bulk)
- Content-Type: application/fhir+ndjson - Use for: Bulk Data `$export` responses only. - Serialization: one resource per line, no envelope.
XML (legacy)
- Content-Type: application/fhir+xml - Use for: legacy integrations, HL7 CDA workflows. - Serialization: namespace-aware XML with attributes for id, elements for other fields.
RDF/Turtle (semantic)
- Content-Type: text/turtle - Use for: semantic web integrations, research federation. - Serialization: RDF triples.
Choice by use case
| Use case | Format |
|---|---|
| Single resource CRUD | JSON |
| Bundle transaction | JSON |
| Bulk export | NDJSON |
| Legacy XML clients | XML |
| Semantic integration | RDF |
| Mobile app | JSON |
| Warehouse ingest | NDJSON |
Server format support
| Server | JSON | NDJSON | XML | RDF |
|---|---|---|---|---|
| HAPI FHIR | Full | Full | Full | Partial |
| Aidbox | Full | Full | Full | External |
| Medplum | Full | Full | External | External |
| Microsoft FHIR Server | Full | Full | Full | External |
Common format mistakes
1. NDJSON as JSON array — wrong; parsers fail. 2. Missing Content-Type header — server may guess wrong. 3. XML without namespaces — non-conformant. 4. Mixing formats in one Bundle — invalid. 5. UTF-8 encoding assumptions violated — spec requires UTF-8.
Format negotiation
HTTP Accept header determines response format. Servers should respect it; clients should be explicit.
Legacy XML support
1. Keep for existing integration partners. 2. Deprecate for new integrations. 3. Plan migration to JSON over time.
FHIR format choice is straightforward given the use case. JSON for CRUD, NDJSON for bulk, XML for legacy, RDF for semantic.
