# Writing Clinical Notes

**Standards status:** Trial-Use (Proposed)
**FHIR version:** R4 (4.0.1)

---

## 1. Purpose and Scope

This page defines a US Core approach to writing **clinical notes** using the FHIR R4 `DocumentReference` resource.

It complements the US Core **[Clinical Notes (read)][1]** guidance (which exposes notes via `DocumentReference` and certain `DiagnosticReport` categories) and adopts conventions used in **[Writing Vital Signs][2]** (SMART scopes, CapabilityStatement documentation, error semantics).

**In scope**

* Create (and optional update) of notes as `DocumentReference`.
* Two modes:
* **Direct Write** (provider-initiated; immediate filing).
* **Mediated Submission** (patient-asserted; server-governed review/promotion).
* Interoperable note typing (LOINC; at least the ten “Common Clinical Notes”).
* MIME and size expectations.
* “Little-p provenance” via native `DocumentReference` fields.
* SMART scopes and server capability discovery.

**Out of scope**

* Stateful/draft workflows (e.g., ambient scribing, continuous audio capture).
* No requirement for FHIR `transaction` support; a single `POST` suffices. FHIR Bundle transactions (`type = "transaction"`) are out of scope for this specification; clients SHALL rely on individual `POST`/`PUT` operations. However, servers MAY support transactions extensionally (e.g., for creating paired resources like `DocumentReference` + `DiagnosticReport`), and clients MAY use them where available.

---

## 2. Relationship to US Core Clinical Notes (read)

US Core **Clinical Notes** requires servers to expose notes through `DocumentReference` and, for some content, also via `DiagnosticReport`.

This write guidance standardizes **writes via `DocumentReference`**. Servers **MAY** also create a paired `DiagnosticReport.presentedForm` to maintain read parity. ([US Core Clinical Notes][1])

---

## 3. Modes of Operation

### Direct Write

* Client `POST`s a `DocumentReference`.
* On success, the note **SHALL** be discoverable through normal search/read.

### Mediated Submission (patient-asserted)

* Client `POST`s a `DocumentReference` with `meta.security` including **`PATAST`**.
* Server **MAY** hold the note for review/promotion.
* Server **MAY** inject `PATAST` by policy (e.g., based on authorization context), even if omitted by the client. Servers that inject **SHOULD** document the conditions.

---

## 4. Required and Must-Support Elements (Expanded)

This write profile builds directly on the **US Core DocumentReference** profile.

### 4.1 References: Author and Encounter

* **Client requirement.** Clients **SHALL** be capable of populating `author` and `context.encounter` when known.
* **How to populate.** The `reference.reference` element SHALL contain either:
* a resolvable relative reference to a resource on the target server (e.g., `"Practitioner/123"`), or
* a contained resource reference (e.g., `"#prac1"`) when a resolvable reference is not possible, or
* an absolute/external reference URL when only an external identifier is available.
* **Display.** Clients **SHOULD** also provide a `display` string for usability.
* **Reference validation (general rule for `author` and `context.encounter`).**
* A server **MAY** require that `DocumentReference.author` and/or `DocumentReference.context.encounter`:
* are present, and
* resolve to local resources of an allowed type.
* If a server has such a requirement for a given element, it **MAY** reject a submission when that element:
* is missing,
* is an absolute/external reference,
* is a syntactically invalid reference, or
* is a relative reference to a local resource that the server can determine does not exist.
* If a server does not have such a requirement for a given element:
* The server **SHALL NOT** reject a submission solely because that element is absent.
* The server **SHALL NOT** reject a submission solely because that element is an absolute/external reference that the server cannot resolve.
* The server **MAY** reject syntactically invalid references and relative references that it can determine point to non-existent resources.
* **Server handling.**
* Servers **SHALL** accept valid references using any of the allowed forms above, subject to their documented business rules.
* Servers **SHOULD** attempt to link to existing entities where possible.
* Servers **MAY** persist contained resource content at their discretion.

### 4.2 Author

* Acceptable resource types: `Practitioner`, `PractitionerRole`, `Organization`, `Device`, `Patient`, `RelatedPerson`.
* For validation rules, see Section 4.1 above.

### 4.3 Context.encounter

* For validation rules, see Section 4.1 above.
* This guide aligns with the US Core `DocumentReference` constraint of maximum cardinality `1` for `context.encounter`. Future versions could revisit this if clear use cases for multiple encounters emerge.

### 4.4 Date handling

* `DocumentReference.date` represents the **time the reference was created** (an `instant`).
* There is no distinct “authored date” element in R4. This specification does not attempt to introduce one.
* The clinically relevant timeframe **SHALL** be expressed using `context.period`.

### 4.5 Identifier

* Clients **SHOULD** supply a stable `identifier`.
* Servers **SHALL** support conditional create (`If-None-Exist`) for idempotency.
* Servers **MAY** deduplicate using identifiers, hashes, or other heuristics.

### 4.6 Content.format

* Clients **SHOULD** populate `content.format` for additional detail.
* Servers **SHALL** persist and round-trip `content.format` when provided.

### 4.7 Other context elements

* Clients **MAY** populate other `context.*` elements.
* Servers **SHALL NOT** reject a submission solely because additional `context.*` elements are present.

### 4.8 Patient-asserted signaling

* Clients **SHALL** include `meta.security` with code `PATAST` when data are patient-supplied.
* Servers **MAY** inject `PATAST` by policy (e.g., based on authorization context). Such behavior **SHALL** be documented.
* Servers **SHALL NOT** require `PATAST` when they can already determine “patient-asserted” status from the authorization context; the flag is for interoperability and downstream consumers.

### 4.9 MIME support

* Servers **SHALL** accept:
* `text/plain; charset=utf-8`
* `application/pdf`
* Servers **SHOULD** accept:
* `application/cda+xml` or `text/xml` when paired with CDA `content.format` codes.
* Servers **MAY** support additional MIME types and **SHOULD** document them.

### 4.10 Size limits

* Servers **SHALL** support HTTP request bodies of at least 7 MiB for `DocumentReference` create and update requests containing inline attachments.
* Within this minimum:
* Servers **SHALL** support inline `Attachment.data` representing source files of at least 5 MiB before base64 encoding.
* Rationale: base64 encoding expands binary content by approximately $4/3$; a 5 MiB source file encodes to about 6.66 MiB, leaving headroom for the FHIR resource envelope within a 7 MiB request.
* Servers **MAY** support higher limits and **SHOULD** document any higher supported limits.
* Servers **SHALL NOT** claim conformance to this specification if they only support limits below these minima.
* Servers **MAY** support larger documents via `Attachment.url` pointing to server-managed content.
* Servers **SHALL NOT** depend on client-hosted URLs in `Attachment.url` for subsequent access; the server is responsible for ensuring ongoing availability of referenced content.

### 4.11 Error handling

* On failed writes, servers **SHALL** return an `OperationOutcome` in the response body with at least one `issue` describing the problem.
* The choice of `issue.code`, `issue.severity`, and narrative content is implementation-specific and MAY indicate, for example, size limit exceeded, invalid references, or local business rule violations.

### 4.12 Status correction

* Servers **SHOULD** allow updates of `status` to `entered-in-error`.
* When using `PUT` to mark `DocumentReference.status = "entered-in-error"`, clients **MAY** send a minimal but valid `DocumentReference` resource including:
* `id` (targeting the existing resource),
* `status` = `entered-in-error`,
* `subject` (for verification),
* and other top-level fields as needed.
* Servers **SHALL NOT** require resubmission of the full original `content` or `context` solely to process a status change.
* Servers **MAY** subsequently exclude such resources from search results by default, but **SHALL** still support read access via direct ID lookup when authorized.

### 4.13 Capability discovery

* Servers **MAY** support the `ValueSet/$expand` operation for discovery of supported codes in this context, as defined in the US Core Clinical Notes guidance:
* https://build.fhir.org/ig/HL7/US-Core/clinical-notes.html#using-expand
* Runtime discovery via `$expand` is not required by this specification.
* Servers **MAY** instead document supported codes, MIME types, and related constraints out-of-band (this is RECOMMENDED where `$expand` is not implemented).

### 4.14 Correction and Replacement

* Clients have two distinct mechanisms for corrections:
* `entered-in-error` for full retractions (see 4.12).
* `relatesTo` with `code` = `replaces` for supersessions.
* When a client needs to supersede an existing document (e.g., revised content without full retraction), they **SHOULD**:
* create a new `DocumentReference` via `POST`, and
* populate `relatesTo` with `code` = `replaces` and `targetReference` pointing to the original resource.
* The new document **SHALL** include the updated content.
* Servers **SHALL** accept incoming `relatesTo` elements on create and round-trip them.
* Servers **MAY** ignore the replacement relationship for local workflow or policy decisions.

---

## 5. Terminology

* **Type.** `DocumentReference.type` uses LOINC where applicable. Servers **SHALL** support at minimum the following LOINC codes for `DocumentReference.type` (the "Common Clinical Notes" from US Core):
- 11488-4: Consultation note
- 11535-2: Discharge summary note
- 11502-2: Operative note
- 11506-3: Progress note
- 34133-9: Summary of episode note
- 34132-1: Summary of death note
- 28655-1: History and physical
- 18842-5: Diagnostic imaging report
- 34745-8: Continuity of care document
- 51848-0: Functional status assessment note

Clients **SHALL** populate these where applicable. For other note types, clients **SHOULD** use LOINC codes when available; servers **MAY** accept additional terminology (e.g., SNOMED) if no suitable LOINC exists, but **SHALL** round-trip them. ([US Core Clinical Notes][1])

* **Category.** Servers **SHALL** support the US Core DocumentReference Category (`clinical-note`). ([US Core DocRef][3])

---

## 6. Authorization (SMART on FHIR)

Servers **SHALL** support SMART v2 scopes for create/update and advertise them in `/.well-known/smart-configuration`. ([Writing Vital Signs][2])

**Recommended granular scopes**

* **Patient-facing:**
* `patient/DocumentReference.c?category=clinical-note`
* `patient/DocumentReference.u?category=clinical-note`
* **Provider/System-facing:**
* `user/DocumentReference.c?category=clinical-note`
* `system/DocumentReference.c?category=clinical-note`
* `user/DocumentReference.u?category=clinical-note`
* `system/DocumentReference.u?category=clinical-note`

---

## 8. API Behavior

**Create**

* `POST [base]/DocumentReference`
* Response:
* `201 Created` on success.
* `202 Accepted` MAY be used for Mediated Submission workflows.

**Update**

* `PUT [base]/DocumentReference/{id}`
* Supported for:
* correcting `status` (e.g., `entered-in-error`) via minimal full-resource updates (see 4.12), and
* other changes consistent with local policy.
* Clients **SHOULD** use `POST` with `relatesTo` (`code` = `replaces`) for document supersessions instead of in-place content overwrites (see 4.14).

---

## 9. Examples

### Direct Write — Provider authored (resolvable Encounter)

{
  "resourceType": "DocumentReference",
  "identifier": [{
    "system": "https://ehr.example.org/doc-ids",
    "value": "CONS-2025-08-21-987"
  }],
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "11488-4",
      "display": "Consultation note"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note"
    }]
  }],
  "subject": { "reference": "Patient/123" },
  "author": [{
    "reference": "PractitionerRole/456",
    "display": "Dr. Rivera (Endocrinology)"
  }],
  "date": "2025-08-22T16:00:00Z",
  "content": [{
    "attachment": {
      "contentType": "text/plain; charset=utf-8",
      "data": "VmlzaXQgc3VtbWFyeS4uLg==",
      "size": 21
    }
  }],
  "context": {
    "encounter": [{
      "reference": "Encounter/enc-789",
      "display": "Office visit 2025-08-21"
    }],
    "period": {
      "start": "2025-08-21",
      "end": "2025-08-21"
    }
  }
}

### Direct Write — Provider authored (contained Encounter)

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "11506-3",
      "display": "Progress note"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note"
    }]
  }],
  "subject": { "reference": "Patient/123" },
  "author": [{ "display": "Dr. Alex Khan" }],
  "contained": [{
    "resourceType": "Encounter",
    "id": "e1",
    "identifier": [{
      "system": "https://ehr.example.org/encounters",
      "value": "E-20250821-42"
    }],
    "period": {
      "start": "2025-08-21T09:00:00Z",
      "end": "2025-08-21T09:30:00Z"
    }
  }],
  "context": {
    "encounter": [{
      "reference": "#e1",
      "display": "Office visit — identifier E-20250821-42"
    }],
    "period": {
      "start": "2025-08-21",
      "end": "2025-08-21"
    }
  },
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "data": "JVBERi0xLjcKJcTl8uXrp/Og0MTGCg==",
      "size": 20480
    }
  }],
  "date": "2025-08-22T14:05:00Z"
}

### Mediated Submission — Patient asserted

{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
      "code": "PATAST",
      "display": "patient asserted"
    }]
  },
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "11506-3",
      "display": "Progress note"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note"
    }]
  }],
  "subject": { "reference": "Patient/123" },
  "contained": [{
    "resourceType": "Device",
    "id": "app1",
    "deviceName": [{
      "name": "Wellness Coach App",
      "type": "manufacturer-name"
    }]
  }],
  "author": [{
    "reference": "#app1",
    "display": "Wellness Coach App"
  }],
  "date": "2025-08-22T14:10:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "data": "JVBERi0xLjcKJcTl8uXrp/Og0MTGCg==",
      "size": 20480
    }
  }],
  "context": {
    "period": {
      "start": "2025-08-20",
      "end": "2025-08-20"
    }
  },
  "identifier": [{
    "system": "https://app.example.org/notes",
    "value": "p-note-20250820-001"
  }]
}

### Status Correction

PUT [base]/DocumentReference/abc

{
  "resourceType": "DocumentReference",
  "id": "abc",
  "status": "entered-in-error",
  "subject": { "reference": "Patient/123" }
}

---

## 10. Conformance Checklist

**Servers**

* [ ] SHALL support create for `DocumentReference`; SHOULD support update.
* [ ] SHALL accept and persist all Mandatory and Must Support elements.
* [ ] SHALL support HTTP request bodies of at least 7 MiB for `DocumentReference` create/update with inline content.
* [ ] SHALL support inline `Attachment.data` representing at least 5 MiB source files.
* [ ] SHALL accept `author` and `context.encounter` using allowed reference patterns, enforcing only documented local requirements (see 4.1).
* [ ] SHALL accept `text/plain; charset=utf-8` and `application/pdf`.
* [ ] SHALL support conditional create (`If-None-Exist`).
* [ ] SHALL document limits, supported formats, and mediated submission policy.
* [ ] SHALL return `OperationOutcome` with at least one `issue` on failed writes.
* [ ] SHALL accept and round-trip `relatesTo` with `code` = `replaces` on create.
* [ ] SHOULD allow `status` updates to `entered-in-error` without requiring full original content.
* [ ] MAY support `Attachment.url` pointing to server-managed content for larger documents.
* [ ] MAY deduplicate using identifiers, hashes, or heuristics.
* [ ] MAY support `ValueSet/$expand` as per US Core Clinical Notes; if not, SHALL document supported codes out-of-band.

**Clients**

* [ ] SHALL supply `status`, `type`, `category`, `subject`, `content`, and `content.attachment.contentType`.
* [ ] SHALL support both inline content and `Attachment.url`.
* [ ] SHALL be capable of populating `author` and `context.encounter` with resolvable, contained, or external references.
* [ ] SHOULD provide stable `identifier`s.
* [ ] SHOULD populate `date`.
* [ ] SHOULD populate `content.format`.
* [ ] SHOULD populate `context.period`.
* [ ] SHOULD include `PATAST` for patient-asserted notes.
* [ ] SHOULD use `relatesTo` = `replaces` for superseding documents instead of overwriting content in place.
* [ ] MAY use `ValueSet/$expand` when supported by servers for discovery of allowed codes.

---

## 11. References

* [US Core Clinical Notes][1]
* [US Core Writing Vital Signs][2]
* [US Core DocumentReference Profile][3]
* [FHIR R4 DocumentReference][4]
* [SMART App Launch v2.2.0 Scopes][5]

[1]: https://build.fhir.org/ig/HL7/US-Core/clinical-notes.html
[2]: https://build.fhir.org/ig/HL7/US-Core/writing-vital-signs.html
[3]: https://build.fhir.org/ig/HL7/US-Core/StructureDefinition-us-core-documentreference.html
[4]: https://hl7.org/fhir/R4/documentreference.html
[5]: https://build.fhir.org/ig/HL7/smart-app-launch/scopes-and-launch-context.html
[formatcodes]: https://hl7.org/fhir/R4/valueset-formatcodes.html# Writing Clinical Notes

**Standards status:** Trial-Use (Proposed)
**FHIR version:** R4 (4.0.1)

## Connectathon discussion / TODOs

* Ensure that a server can enforce a business rule like "encouners are required for documentreferences" and in this case it would be OK to reject a submission.. but if a server doesn't require an encounter, it shouldn't reject a submission jsut because a non-resolvable encounter reference is provided. The current language is ... unclear or not consistent with this.

* Write size limits in terms of full body size. Explain motivation is enabling submitting text/PDF/etc **files up to 5MB** and the math says 5*4/3 (base64) + 100KB (fhir shell) ~= (rounding up) 7MB total HTTP request body size. So our spec should **require servers to support bodies up to 7MB total body size attachment.data strings up to 6.66MB within that body.

file on disk: 5MB
base 64 encode and stick in attachment.data: 4/3 * 5MB

* Validation of authors/encounters -- it shoudl be OK to reject an invalid relative refernce (i.e. this is a case where the sever can prove it's wrong) but an external reference should be treated as OK to the extent that the server's busness rules make the field optional (like, if you're Ok with no reference at all, you shouldn't blow up when you see an extenral reference that you're unable to interpret)

* We didn't include scenarios for valuset expand -- only Epic supports this today, but they don't have a way to say "GET [base]/ValueSet/$expand?context=[context]&contextDirection=[contextDirection]" as documented in US Core; they require additinally specifying which DocRef.category you're askign about (currently implemted as a "filter" param to the $expand operation, which is a bit ad-hoc and not obviously right). May want follow-up to determine how to answer the question: "Which codes do you support in this context slot _when some other field in the resource has a specific value of X_ ". We could try to go deeper on this, but it's not clear how useful runtime discover even is... vs having the server just publish good documentation for client devs ahead of time.

* Gino: Could add a "category" parameter in the US Core... profile?... on $expand
* Eric: Or we could define a new custom operation; using $expand is a bit of kludge
* Cooper: I'm not convinced this functionality is even useful at all. Health Info Mgmt departments will often decide what to support, and if a new app needs something they may be making a request that the health system will need to decide about and enable. So if this decision process exists in the middle, runtime discovery isn't valuable.
* Gino: Runtime discovery can help when there are proxy servers, holding tanks, etc in the mix

* Connectathon testing was largely open servers (only 1 with SMART on FHIR authz)

* Eric: US Core limits `.context.encounter` to max cardinality of `1`, but the base spec allows `*`. Do we want to keep it limited?
* Cooper: The USCDI note types seem naturally "1 encouter"
* Eric: But we may want to lay groundwork more generally
* Cooper: For care coordination I could see the potential
* Brett: Would want to hear a use case for expansion
* Eric: was it even a conscious decision to constrain?
// end connectathon discussion

---

## 1. Purpose and Scope

This page defines a US Core approach to writing **clinical notes** using the FHIR R4 `DocumentReference` resource.

It complements the US Core **[Clinical Notes (read)][1]** guidance (which exposes notes via `DocumentReference` and certain `DiagnosticReport` categories) and adopts conventions used in **[Writing Vital Signs][2]** (SMART scopes, CapabilityStatement documentation, error semantics).

**In scope**

* Create (and optional update) of notes as `DocumentReference`.
* Two modes:
* **Direct Write** (provider-initiated; immediate filing).
* **Mediated Submission** (patient-asserted; server-governed review/promotion).
* Interoperable note typing (LOINC; at least the ten “Common Clinical Notes”).
* MIME and size expectations.
* “Little-p provenance” via native `DocumentReference` fields.
* SMART scopes and server capability discovery.

**Out of scope**

* Stateful/draft workflows (e.g., ambient scribing, continuous audio capture).
* No requirement for FHIR `transaction` support; a single `POST` suffices. FHIR Bundle transactions (type='transaction') are out of scope for this specification; clients SHALL rely on individual `POST`/`PUT` operations. However, servers MAY support transactions extensionally (e.g., for creating paired resources like `DocumentReference` + `DiagnosticReport`), and clients MAY use them where available.
---

## 2. Relationship to US Core Clinical Notes (read)

US Core **Clinical Notes** requires servers to expose notes through `DocumentReference` and, for some content, also via `DiagnosticReport`.

This write guidance standardizes **writes via `DocumentReference`**. Servers **MAY** also create a paired `DiagnosticReport.presentedForm` to maintain read parity. ([US Core Clinical Notes][1])

---

## 3. Modes of Operation

### Direct Write

* Client `POST`s a `DocumentReference`.
* On success, the note **SHALL** be discoverable through normal search/read.

### Mediated Submission (patient-asserted)

* Client `POST`s a `DocumentReference` with `meta.security` including **`PATAST`**.
* Server **MAY** hold the note for review/promotion.
* Server **MAY** inject `PATAST` by policy (e.g., based on authorization context), even if omitted by the client. Servers that inject **SHOULD** document the conditions.

---

## 4. Required and Must-Support Elements (Expanded)

This write profile builds directly on the **US Core DocumentReference** profile.

### 4.1 References: Author and Encounter

* **Client requirement.** Clients **SHALL** be capable of populating `author` and `context.encounter` when known.
* **How to populate.** The `reference.reference` element SHALL contain either:

* a **resolvable relative reference** to a resource on the target server (e.g., `"Practitioner/123"`), or
* a **contained resource** reference (e.g., `"#prac1"`) when a resolvable reference is not possible.
* **Display.** Clients **SHOULD** also provide a `display` string for usability.
* **Server handling.** Servers **SHALL** accept either approach. They **SHOULD** attempt to match to existing entities, and **MAY** persist contained resource content at their discretion.
* **Non-blocking.** Servers **SHALL NOT** reject a submission solely because the reference cannot be resolved.

### 4.2 Author

* Acceptable resource types: `Practitioner`, `PractitionerRole`, `Organization`, `Device`, `Patient`, `RelatedPerson`.

### 4.3 Context.encounter

* Servers SHALL accept either a resolvable encounter reference or a contained `Encounter` reference.
* Business rules MAY require an encounter association, but servers SHALL NOT reject merely because the reference is not resolvable.

### 4.4 Date handling

* `DocumentReference.date` represents the **time the reference was created** (an `instant`).
* There is **no distinct “authored date”** element in R4. This specification does not attempt to introduce one.
* The **clinically relevant timeframe** SHALL be expressed using `context.period`.

### 4.5 Identifier

* Clients **SHOULD** supply a stable `identifier`.
* Servers **SHALL** support conditional create (`If-None-Exist`) for idempotency.
* Servers **MAY** deduplicate using identifiers, hashes, or other heuristics.

### 4.6 Content.format

* Clients **SHOULD** populate `content.format` for additional detail.
* Servers **SHALL** persist and round-trip when provided.

### 4.7 Other context elements

* Clients MAY populate other `context.*` elements.
* Servers SHALL NOT reject because they are present.

### 4.8 Patient-asserted signaling

* Clients **SHALL** include `meta.security` with code `PATAST` when data are patient-supplied.
* Servers **MAY** inject `PATAST` by policy.

### 4.9 MIME support

* Servers **SHALL** accept: `text/plain; charset=utf-8`, `application/pdf`.
* Servers **SHOULD** accept: `application/cda+xml` or `text/xml` when paired with CDA `content.format` codes.

### 4.10 Size limits

* Servers **SHALL** accept inline attachments up to at least **5 MiB**.
* Servers **MAY** support submission via `.attachment.url` that point to larger files than this
* Servers **SHALL NOT** link to client-supplied URLs for subsequent readers.
* Servers **SHALL** document size limits in their API documentation.

### 4.11 Error handling

* On failed writes, servers **SHOULD** return an `OperationOutcome`.

### 4.12 Status correction

* Servers **SHOULD** allow updates of `status` to `entered-in-error`.
* Clients MAY submit a partial `PUT` request to a `DocumentReference` resource, including only the `id`, `status` (set to 'entered-in-error'), `subject` (for verification), and other top-level fields as needed—omitting the full content or context. Servers SHALL accept such partial updates without requiring the original document content and SHOULD transition the resource's status accordingly. Servers MAY subsequently exclude the resource from search results (e.g., to limit visibility), but SHALL still support read access via direct ID lookup if authorized.

### 4.13 Capability discovery

* Servers **SHOULD** support the FHIR `ValueSet/$expand` operation with `contextDirection=incoming` to enable client discovery of supported note and report categories/codes (e.g., LOINC for `DocumentReference.type`). See the US Core Clinical Notes IG for details on invocation (e.g., contexts for `us-core-documentreference` category/type and equivalent `DiagnosticReport` elements): https://build.fhir.org/ig/HL7/US-Core/clinical-notes.html#using-expand. Note that discovery of supported MIME types (section 4.9) and content formats (section 4.6) is separate and out-of-band: Servers SHALL document these in their API documentation, including any limits or extensions beyond the minima in this specification.

### 4.14 Correction and Replacement

* Clients have two distinct mechanisms for corrections: entered-in-error for full retractions (see 4.12) and replacement for supersessions (below). These provide technical signals of "this was a mistake" or "this document replaces that one," respectively. Downstream handling (e.g., archiving, notifications, visibility to readers) is out of scope and a server policy decision.
* When a client needs to supersede an existing document (e.g., due to revisions without full retraction), they SHOULD create a new `DocumentReference` via `POST` and populate `relatesTo` with `code` = 'replaces' and `targetReference` to the original resource's ID. The new document SHALL include the updated content.
* Servers SHALL accept incoming `relatesTo` elements on create (and round-trip them) but MAY ignore the relationship for local policy decisions.

---

## 5. Terminology

* **Type.** `DocumentReference.type` **SHALL** use LOINC and support at minimum the ten **Common Clinical Notes**. Servers SHALL support at minimum the following LOINC codes for `DocumentReference.type` (the 'Common Clinical Notes' from US Core):

- 11488-4: Consultation note
- 11535-2: Discharge summary note
- 11502-2: Operative note
- 11506-3: Progress note
- 34133-9: Summary of episode note
- 34132-1: Summary of death note
- 28655-1: History and physical
- 18842-5: Diagnostic imaging report
- 34745-8: Continuity of care document
- 51848-0: Functional status assessment note

Clients SHALL use these where applicable. For other note types, clients SHOULD use LOINC codes when available; servers MAY accept additional terminology (e.g., SNOMED) if no suitable LOINC exists, but SHALL round-trip them. ([US Core Clinical Notes][1])
* **Category.** Servers **SHALL** support the US Core DocumentReference Category (`clinical-note`). ([US Core DocRef][3])

---

## 6. Authorization (SMART on FHIR)

Servers **SHALL** support SMART v2 scopes for create/update and advertise them in `/.well-known/smart-configuration`. ([Writing Vital Signs][2])

**Recommended granular scopes**

* **Patient-facing:**

* `patient/DocumentReference.c?category=clinical-note`
* `patient/DocumentReference.u?category=clinical-note`
* **Provider/System-facing:**

* `user/DocumentReference.c?category=clinical-note`
* `system/DocumentReference.c?category=clinical-note`
* `user/DocumentReference.u?category=clinical-note`
* `system/DocumentReference.u?category=clinical-note`

---

## 8. API Behavior

**Create**

* `POST [base]/DocumentReference`
* Response: `201 Created` (success), or `202 Accepted` (for Mediated Submission).

**Update**

* `PUT [base]/DocumentReference/{id}`
* Supported for correcting status (e.g., `entered-in-error`) via partial updates (see 4.12) or other changes. Clients SHOULD use `POST` with `relatesTo` (code='replaces') for document supersessions instead of in-place content updates (see 4.14).

---

## 9. Examples

### Direct Write — Provider authored (resolvable Encounter)

{
  "resourceType": "DocumentReference",
  "identifier": [{ "system": "https://ehr.example.org/doc-ids", "value": "CONS-2025-08-21-987" }],
  "status": "current",
  "type": { "coding": [{ "system": "http://loinc.org", "code": "11488-4", "display": "Consultation note" }] },
  "category": [{ "coding": [{ "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category", "code": "clinical-note" }] }],
  "subject": { "reference": "Patient/123" },
  "author": [{ "reference": "PractitionerRole/456", "display": "Dr. Rivera (Endocrinology)" }],
  "date": "2025-08-22T16:00:00Z",
  "content": [{
    "attachment": {
      "contentType": "text/plain; charset=utf-8",
      "data": "VmlzaXQgc3VtbWFyeS4uLg==",
      "size": 21
    }
  }],
  "context": {
    "encounter": [{ "reference": "Encounter/enc-789", "display": "Office visit 2025-08-21" }],
    "period": { "start": "2025-08-21", "end": "2025-08-21" }
  }
}

### Direct Write — Provider authored (contained Encounter)

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": { "coding": [{ "system": "http://loinc.org", "code": "11506-3", "display": "Progress note" }] },
  "category": [{ "coding": [{ "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category", "code": "clinical-note" }] }],
  "subject": { "reference": "Patient/123" },
  "author": [{ "display": "Dr. Alex Khan" }],
  "contained": [{
    "resourceType": "Encounter",
    "id": "e1",
    "identifier": [{ "system": "https://ehr.example.org/encounters", "value": "E-20250821-42" }],
    "period": { "start": "2025-08-21T09:00:00Z", "end": "2025-08-21T09:30:00Z" }
  }],
  "context": {
    "encounter": [{ "reference": "#e1", "display": "Office visit — identifier E-20250821-42" }],
    "period": { "start": "2025-08-21", "end": "2025-08-21" }
  },
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "data": "JVBERi0xLjcKJcTl8uXrp/Og0MTGCg==",
      "size": 20480
    }
  }],
  "date": "2025-08-22T14:05:00Z"
}

### Mediated Submission — Patient asserted

{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue", "code": "PATAST", "display": "patient asserted" }]
  },
  "status": "current",
  "type": { "coding": [{ "system": "http://loinc.org", "code": "11506-3", "display": "Progress note" }] },
  "category": [{ "coding": [{ "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category", "code": "clinical-note" }] }],
  "subject": { "reference": "Patient/123" },
  "contained": [{
    "resourceType": "Device",
    "id": "app1",
    "deviceName": [{ "name": "Wellness Coach App", "type": "manufacturer-name" }]
  }],
  "author": [{ "reference": "#app1", "display": "Wellness Coach App" }],
  "date": "2025-08-22T14:10:00Z",
  "content": [{
    "attachment": { "contentType": "application/pdf", "data": "JVBERi0xLjcKJcTl8uXrp/Og0MTGCg==", "size": 20480 }
  }],
  "context": { "period": { "start": "2025-08-20", "end": "2025-08-20" } },
  "identifier": [{ "system": "https://app.example.org/notes", "value": "p-note-20250820-001" }]
}

### Status Correction

PUT [base]/DocumentReference/abc

{ "resourceType": "DocumentReference", "id": "abc", "status": "entered-in-error", "subject": { "reference": "Patient/123" } }

---

## 10. Conformance Checklist

**Servers**

* [ ] SHALL support create for `DocumentReference`; SHOULD support update.
* [ ] SHALL accept & persist all Mandatory and Must Support elements.
* [ ] SHALL accept inline content up to at least 5 MiB.
* [ ] SHALL accept `author` and `context.encounter` either as resolvable relative references or contained resources, with optional `display`.
* [ ] SHALL accept `text/plain; charset=utf-8` and `application/pdf`.
* [ ] SHALL support conditional create (`If-None-Exist`).
* [ ] SHALL document limits and mediated submission policy.
* [ ] SHALL accept partial `PUT`s for `status` = 'entered-in-error' without full content; SHOULD transition status and MAY suppress from searches.
* [ ] SHALL accept and round-trip `relatesTo` with `code` = 'replaces' on create; MAY ignore for policy.
* [ ] SHOULD return `OperationOutcome` on failed writes and when limits are exceeded.
* [ ] SHOULD allow `status` updates to `entered-in-error`.
* [ ] MAY support URLs for content with higher limits.
* [ ] MAY deduplicate using identifiers, hashes, or heuristics.

**Clients**

* [ ] SHALL supply `status`, `type`, `category`, `subject`, `content`, and `content.attachment.contentType`.
* [ ] SHALL support both inline and URL content.
* [ ] SHALL be capable of populating `author` and `context.encounter` with either resolvable or contained references.
* [ ] SHOULD provide stable identifiers.
* [ ] SHOULD populate `date`.
* [ ] SHOULD populate `content.format`.
* [ ] SHOULD populate `context.period`.
* [ ] SHOULD include `PATAST` for patient-asserted notes.
* [ ] SHOULD use `relatesTo` = 'replaces' for superseding documents instead of in-place updates.
* [ ] SHOULD use `ValueSet/$expand?contextDirection=incoming` for type discovery per US Core guidance.

---

## 11. References

* [US Core Clinical Notes][1]
* [US Core Writing Vital Signs][2]
* [US Core DocumentReference Profile][3]
* [FHIR R4 DocumentReference][4]
* [SMART App Launch v2.2.0 Scopes][5]

---

[1]: https://build.fhir.org/ig/HL7/US-Core/clinical-notes.html
[2]: https://build.fhir.org/ig/HL7/US-Core/writing-vital-signs.html
[3]: https://build.fhir.org/ig/HL7/US-Core/StructureDefinition-us-core-documentreference.html
[4]: https://hl7.org/fhir/R4/documentreference.html
[5]: https://build.fhir.org/ig/HL7/smart-app-launch/scopes-and-launch-context.html
[formatcodes]: https://hl7.org/fhir/R4/valueset-formatcodes.html

---