Composition — FHIR clinical document

The FHIR equivalent of an HL7 CDA clinical document: discharge summary, IPS (International Patient Summary), operative note, electronic prescription. Composition is the logical root of any FHIR document.

Purpose of the resource

Composition represents healthcare-related information assembled into a single logical package with clinical attestation. It's the FHIR equivalent of a "document" in the HL7 CDA sense: a coherent, signed set of data published at a point in time, legally binding.

A Composition must always be wrapped in a Bundle of type document for exchange: the Bundle physically contains the Composition (always in first position) plus every resource referenced by the Composition (Patient, AllergyIntolerance, Condition…). This wrapper guarantees document atomicity: everything the Composition cites is in the same Bundle.

The HL7 + CEN/TC 251 International Patient Summary (IPS) IG uses Composition as its root. So do French (ANS CR-Hospi), US (US Core Discharge Summary), German (MIO), and UK (NHS Care Connect) national profiles.

Key fields

Field	Type	Cardinality	Role
`url`	uri	0..1	Canonical URL of the Composition (rare in practice).
`identifier`	Identifier[]	0..*	External document identifiers (report number, UUID…).
`version`	string	0..1	Document version.
`status`	code	1..1	Mandatory. Document state. Modifier.
`type`	CodeableConcept	1..1	Mandatory. Document type (LOINC code).
`category`	CodeableConcept[]	0..*	Document categories.
`subject`	Reference(any)[]	0..*	Document subject(s) — typically the Patient.
`encounter`	Reference(Encounter)	0..1	Encounter where the document was produced.
`date`	dateTime	1..1	Mandatory. Publication datetime.
`useContext`	UsageContext[]	0..*	Usage context (target population, parameters).
`author`	Reference(Practitioner \| PractitionerRole \| Device \| Patient \| RelatedPerson \| Organization)[]	1..*	Mandatory. Document author(s).
`title`	string	1..1	Mandatory. User-facing title.
`attester`	BackboneElement[]	0..*	Clinical attestation(s) — who legally validates the document.
`custodian`	Reference(Organization)	0..1	Organisation responsible for document custody.
`relatesTo`	BackboneElement[]	0..*	Links to other documents (replacement, complement, appendix).
`event`	BackboneElement[]	0..*	Documented event(s).
`section`	BackboneElement[]	0..*	Document sections (allergies, medication, problems…), recursive via `section.section`.

Document statuses

The status code is mandatory and carries the document lifecycle (Required binding):

Code	Meaning
`registered`	Registered but not yet validated.
`partial`	Partially complete.
`preliminary`	Preliminary — revision possible.
`final`	Final — validated, binding.
`amended`	Amended after validation.
`corrected`	Corrected (previous error).
`appended`	Extended by addition.
`cancelled`	Cancelled.
`entered-in-error`	Erroneous entry.
`deprecated`	Obsolete (replaced).
`unknown`	Unknown status.

JSON example

IPS-type Composition (Patient Summary, LOINC 60591-5) for Peter Chalmers, with three sections: allergies, active medication, active problems. Final document legally attested by the author.

json composition-example.json

{
  "resourceType": "Composition",
  "id": "example",
  "identifier": [{
    "system": "urn:ietf:rfc:3986",
    "value": "urn:uuid:1a2b3c4d-5e6f-7890-abcd-ef1234567890"
  }],
  "status": "final",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "60591-5",
      "display": "Patient summary Document"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://loinc.org",
      "code": "11369-6",
      "display": "History of Immunization Narrative"
    }]
  }],
  "subject": [{ "reference": "Patient/example", "display": "Peter Chalmers" }],
  "encounter": { "reference": "Encounter/example" },
  "date": "2026-05-14T15:30:00+02:00",
  "author": [
    { "reference": "Practitioner/example", "display": "Dr Adam Careful" }
  ],
  "title": "International Patient Summary — Peter Chalmers",
  "attester": [{
    "mode": {
      "coding": [{
        "system": "http://hl7.org/fhir/composition-attestation-mode",
        "code": "legal",
        "display": "Legal"
      }]
    },
    "time": "2026-05-14T15:30:00+02:00",
    "party": { "reference": "Practitioner/example" }
  }],
  "custodian": { "reference": "Organization/hosp01" },
  "section": [{
    "title": "Allergies and intolerances",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "48765-2",
        "display": "Allergies and adverse reactions Document"
      }]
    },
    "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Penicillin — moderate skin reaction, 2019.</p></div>"
    },
    "entry": [{ "reference": "AllergyIntolerance/example" }]
  }, {
    "title": "Active medication",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "10160-0",
        "display": "History of Medication use Narrative"
      }]
    },
    "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Metformin 1000 mg, twice a day.</p></div>"
    },
    "entry": [{ "reference": "MedicationStatement/example" }]
  }, {
    "title": "Active problems",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "11450-4",
        "display": "Problem list - Reported"
      }]
    },
    "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Type 2 diabetes, diagnosed May 2026.</p></div>"
    },
    "entry": [{ "reference": "Condition/example-diabetes" }]
  }]
}

Worth pointing out in this example:

status=final + attester[mode=legal] = legally binding document.
The type LOINC 60591-5 precisely identifies an IPS Patient Summary.
Each section carries a title, a LOINC code, a text.div (human-readable XHTML), and entry[] pointing to underlying structured resources.
The text.div of each section must faithfully reflect the content of the entry: this is the attestation-by-narrative rule — what the attester saw and signed.

Document Bundle

To exchange a Composition, wrap it in a Bundle:

{
  "resourceType": "Bundle",
  "type": "document",
  "identifier": { "system": "urn:ietf:rfc:3986", "value": "urn:uuid:..." },
  "timestamp": "2026-05-14T15:30:00+02:00",
  "entry": [
    { "fullUrl": "...", "resource": { "resourceType": "Composition", ... } } ,
    { "fullUrl": "...", "resource": { "resourceType": "Patient", ... } } ,
    { "fullUrl": "...", "resource": { "resourceType": "AllergyIntolerance", ... } } ,
    { "fullUrl": "...", "resource": { "resourceType": "MedicationStatement", ... } } ,
    { "fullUrl": "...", "resource": { "resourceType": "Condition", ... } }
  ]
}

Three golden rules of the document Bundle:

The Composition is required to be the first entry (Bundle.entry[0].resource).
Every resource referenced by the Composition (Patient, AllergyIntolerance…) must be in the Bundle, by fullUrl.
The Bundle may be signed (XML-DSig or JWS) to guarantee document integrity.

Common pitfalls

Missing status, type, date, author, title — all mandatory (cardinality 1..*). Without them, the document is rejected.
Composition sent outside a Bundle — technically the resource stands alone, but for document exchange, the IPS IG and most profiles require the Bundle document wrapper.
Missing or inconsistent text.div vs entry — the narrative is the attested element. If it doesn't match the structured entries, the document is legally inconsistent.
No attester on a final document — for medico-legal usage, at least one mode=legal or professional attestation is expected.
References to resources outside the Bundle — every Reference must resolve within the Bundle. An absolute external reference (e.g. https://server/Patient/123) breaks document atomicity.
Empty sections — IPS requires certain sections (Allergies, Medication, Problems) to be present, and if empty, to carry explicit text ("No known allergies"). Silent emptiness is forbidden.
Multiple versions without relatesTo — an amended Composition (status=amended) must point to the previous version via relatesTo.targetReference with code=replaces.

Bundle — mandatory document wrapper for exchange (type=document).
Patient — typical subject referenced by subject.
Practitioner, PractitionerRole, Organization — authors and custodian.
AllergyIntolerance, MedicationStatement, Condition, Observation, Procedure, Immunization — resources typically included in IPS sections.
DocumentReference — document index, can reference a Composition via content.attachment.url.
Encounter — context of document production.

Foundations

Standards

Flagship messages

Tools

Composition — FHIR clinical document

Purpose of the resource

Key fields

Document statuses

JSON example

Document Bundle

Common pitfalls

Composition — FHIR clinical document

Purpose of the resource

Key fields

Document statuses

JSON example

Document Bundle

Common pitfalls

Related resources