# Writing Clinical Notes - US Core Implementation Guide v9.0.0

* [**Table of Contents**](toc.md)
* [**Looking Ahead**](looking-ahead.md)
* **Writing Clinical Notes**

## Writing Clinical Notes

| |
| :--- |
| *Page standards status:*[Informative](http://hl7.org/fhir/R4/versions.html#std-process) |

The conformance verbs used below describe the intended semantics if the content is adopted, but they carry no US Core conformance or certification requirements until the page standards status changes from 'informative'.

### 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](clinical-notes.md)** guidance and adopts conventions used in **[Writing Vital Signs](writing-vital-signs.md)** (SMART scopes, CapabilityStatement documentation, error semantics).

**In scope**

* Create (and optionally update) notes as `DocumentReference` resources.
* 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.

-------

### Relationship to US Core Clinical Notes

[US Core Clinical Notes](clinical-notes.md) 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.

-------

### Modes of Operation

#### Direct Write

Provider writes directly to the clinical system via a provider-facing app.

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

**Example Scenario:** A provider uses a SMART on FHIR risk assessment app during a patient encounter. The app calculates a cardiovascular risk score, and the provider clicks "Save to Chart" to write the assessment report directly into the patient's record as a progress note. The EHR associates the note with the current encounter.

#### Mediated Submission (patient-asserted)

Patient mediates the exchange of a clinical note from one provider to another via a patient-facing app or a note authored by a patient-facing app.

* Client `POST`s a `DocumentReference` with a `meta.security` code "PATAST".
* Server **MAY** hold the note for review/promotion.
* Server **MAY** add the `meta.security` code "PATAST" by policy (e.g., based on authorization context), even if it is omitted by the client, and **SHOULD** document this behavior.

**Example Scenarios:**

1. A patient retrieves a consultation note from their specialist's EHR using a patient-facing app, then writes it to their primary care provider's EHR.
1. A patient uses a wellness app to document symptoms and self-management activities. The app writes this information to the patient's EHR as a patient-asserted note (tagged with "PATAST").

-------

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

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

#### 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:
* **Display.** Clients **SHOULD** also provide a `display` string for usability.
* **Server handling.** Servers **SHALL** accept either approach. They **SHOULD** attempt to match references 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.

#### Author

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

#### 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.

#### 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`.

#### 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.

#### Content.format

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

#### Other context elements

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

#### Patient-asserted signaling

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

#### 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.

#### Size limits

* Servers **SHALL** accept inline attachments up to at least **5 MiB**.
* Servers **MAY** support submissions via `.attachment.url` that points 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.

#### Error handling

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

#### 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.

#### 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 [US Core Clinical Notes](clinical-notes.md) 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.

#### 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.

-------

### 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):


  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](clinical-notes.md))
* **Category.** Servers **SHALL** support the US Core DocumentReference Category (`clinical-note`). ([US Core DocRef](StructureDefinition-us-core-documentreference.md))

-------

### Authorization (SMART on FHIR)

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

**Recommended granular scopes**

* **Patient-facing:**
* **Provider/System-facing:**

-------

### 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).

-------

### 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" } }

```

-------

### 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 a `meta.security` code "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.

-------

### References

* [US Core Clinical Notes](clinical-notes.md)
* [US Core Writing Vital Signs](writing-vital-signs.md)
* [US Core DocumentReference Profile](StructureDefinition-us-core-documentreference.md)
* [FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html)
* [SMART App Launch v2.2.0 Scopes](https://build.fhir.org/ig/HL7/smart-app-launch/scopes-and-launch-context.html)

-------

-------

