US Core Implementation Guide
9.0.0 - STU 9 US

US Core Implementation Guide - Downloaded Version 9.0.0 See the Directory of published versions

## Writing Clinical Notes

Page standards status: Informative

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 guidance and adopts conventions used in Writing Vital Signs (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 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.
2. 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:

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

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

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

### Authorization (SMART on FHIR)

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

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`

### 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
- US Core Writing Vital Signs
- US Core DocumentReference Profile
- FHIR R4 DocumentReference
- SMART App Launch v2.2.0 Scopes