US Core Implementation Guide
10.0.0-ballot - STU 10 Ballot
United States of America
US Core Implementation Guide
10.0.0-ballot - STU 10 Ballot
United States of America
US Core Implementation Guide, published by HL7 International / Cross-Group Projects. This guide is not an authorized publication; it is the continuous build for version 10.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/US-Core/ and changes regularly. See the Directory of published versions
| 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'.
This page replaces the US Core Writing Clinical Notes.
This page defines a US Core approach to writing any document type, such as clinical notes, insurance cards, and advance directives to a FHIR server as DocumentReference resources. It does not change how servers return documents in searches. It complements the US Core Clinical Notesguidance and adopts conventions used in Writing Vital Signs and the Continuous Glucose Monitoring Implementation Guide.
create
PATAST security label.ServiceRequest. The submitted document references that request in context.related. Provider Writes are always treated as solicited.This documentation establishes client and server rules and guidance for writing documents to a FHIR server. The FHIR RESTful create transport mechanism refers to the ability of a client to instantiate a new resource via HTTP POST. It builds directly on the US Core DocumentReference profile and US Core Clinical Notes guidance. This mechanism allows for simple exchange in scenarios where no additional resources are necessary.
$submit-bundle OperationServers have the option of supporting the $submit-bundle Operation. It allows additional FHIR resources to be submitted by the client but permits partial acceptance by server. Servers process the DocumentReference under the same rules as one submitted with RESTful create, including the processing expectation, submission modes, solicitation, and documented support.
The following table summarizes the conformance rules for writing DocumentReference with one row per rule and one column per mode
*TODO generate from the markdown text.*
Servers accept only the documents that the organization will actually process or review. Patients usually assume that a submitted document reaches their care team. Accepting content that no one will process or review creates a false expectation.
Requirements
create for DocumentReference.DocumentReference category or type that the organization cannot or does not intend to process or review.201 Created with a Location header when the document is available on return.202 Accepted when it is held for review.OperationOutcome on failed writesGuidance
"Process or review" includes filing an insurance card that sits unexamined for months, routing a document to a later review queue, and rejecting content the deployment cannot handle. A person does not need to inspect every submission. See the Document Type and Category below for specific guidance on categories and types. To comply with the US Core Clinical Notes requirements, servers are required to also create DiagnosticReport instances for certain scanned report types.
Whether the server returns a 201 Created or a 202 Accepted depends on the Submission mode:
| Submission Mode | Response | Available through read and search |
|---|---|---|
| Provider Write (always solicited) | 201 Created |
Immediately |
| Patient Solicited | 201 Created |
Immediately |
| Patient Unsolicited | 201 Created or 202 Accepted |
Server policy |
See the Submission Modes Section below for further guidance and examples.
For integrated-application workflows (e.g., provider-facing apps), capabilities are negotiated while working through integration and runtime advertisement and client discovery is not needed. However, for patient-facing applications, runtime advertisement and client discovery are critical to proper function.
Requirements
$submit-bundle support, and review policy.ValueSet/$expand with contextDirection=incoming.Guidance
The rules on this page do not require a server to support any particular category, type, or MIME type. See the Document Type and Category below for specific guidance on these parameters. How a Client can determine the note and report types supported by a server using the ValueSet/$expand operation is described on the Clinical Notes page.
Note that the FHIR R5 based Application Feature Framework can also express support and enumerate specific types and categories. A worked example is provided here
This section builds directly on the US Core DocumentReference profile. It adds the following rules, guidance, and terminology to facilitate document write exchange. Note that this guidance also aligns with the US Core ADI DocumentReference Profile.
All US Core Profiles identify elements with a must support flag that imposes conformance requirements on both the client and server. However, the [US Core Must Support] definition is framed entirely in terms of requesters and responders - reading or returning data. None of its provisions is scoped to writing. The following clarifications apply for the purposes of this guidance:
DocumentReference that omits a must-support element is still conformant.The DocumentReference.type and DocumentReference.category elements are necessary for understanding what the document is. They are used by a server to advertise support and by a client to identify the contents of its submission.
category is the broad classification used to determine what kind of data is being presented. It is the primary signal for routing, for workflow selection, and as the entry point for discovering supported types. A DocumentReference instance can have multiple categories.type is the specific classification used to identify the exact contents of the document. A DocumentReference instance can only have one type and is bound to LOINC Documents types or the concept 'unknown'.Client Requirements
category and a type on submission.Server Requirements
Guidance
type codes for each supported category such that a patient is capable of selecting appropriate content. A server is not expected to accept categories and types it does not natively support.type and category are CodeableConcept datatypes, clients might populate the specific advertised coding and include the other codes in the same coding array as translations.The codes listed in this section are a starter set of recommendations, not conformance requirements. A server might use some of them or support codes that do not appear here. Actual support is established by what a server documents and advertises.
The US Core DocumentReference Category value set, currently contains one concept, clinical-note, and the US Core ADI DocumentReference Profile, currently lists only 42348-3 (Advance Healthcare Directives).
The recommended categories below addresses what the document is for which drives routing, workflow, and the type discovery described in this guidance.
| Row | Code | System | Display | Definition |
|---|---|---|---|---|
| 1 | clinical-note |
http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category |
Clinical Note | existing Purpose - Clinical Note |
| 2 | 42348-3 |
http://loinc.org |
Advance Healthcare Directives | existing Purpose - Advance Healthcare Directives |
| 3 | medical-history |
http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category |
Medical History | Purpose - Medical History |
| 4 | insurance-document |
http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category |
Insurance or Coverage related documentation | Purpose - Insurance or Coverage related documentation |
| 5 | identity-document |
http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category |
Identity documentation | Purpose - Identity documentation |
The US Core DocumentReference Profile document.type has a required binding to the US Core Clinical Note Type value set, which is composed of LOINC Documents types plus the concept "unknown". (the US Core DocumentReference ADI Profile Advance Healthcare Directive Categories value set is a subset).
The recommended types below are grouped by category.
Category clinical-note: The US Core Clinical Notes page defines the eleven Common Clinical Notes types. For other note types, use codes from the US Core Clinical Note Type valueset.
Category LOINC 42348-3 (Advance healthcare directives): Use LOINC codes drawn from the Advance Healthcare Directive Categories value set.
Categories medical-history, insurance-document, and identity-document: - Supported types are established entirely through server advertisement and are drawn from the US Core Clinical Note Type value set.
For example:
| Category | Code | Display |
|---|---|---|
insurance-document / identity-document |
64290-0 |
Health insurance card |
medical-history |
73985-4 |
Exercise activity |
medical-history |
55424-6 |
Calories burned in unspecified time by Pedometer |
US Core DocumentReference Profile required binding on DocumentReference.type means a submission with no conformant coding cannot satisfy the US Core profile.
Where a document type genuinely has no suitable LOINC code and uses a local concept, a server might choose to support that submission as a non-conformant US Core profile.
Alternatively, to satisfy the required binding, a locally-defined coding can be accompanied by a generic "catch-all" coding from the value set as a code translation. For example, the following LOINC codes:
| Category | Code | Display |
|---|---|---|
medical-history |
11503-0 | Medical records |
medical-history |
47045-0 | Study report |
When reading documents, a server commonly collapses several internal document types into a single standard code - for example, mapping ten local progress note variants onto LOINC 11506-3. That collapse is lossy and cannot be reversed on write: a server receiving only 11506-3 has no way to recover whether the source meant a pediatric or an adult progress note, and is forced to select a default.
The submitting system usually knows the correct granular answer. By populating the most specific advertised type coding, and including a more specific code in the same type.coding array as a translation, the granularity is preserved.
Client Requirements
author and context.encounter when they are known.author.reference and context.encounter.reference with either a relative reference to a resource on the server or a reference to a contained resource.author.display and context.encounter.display.Server Requirements
author and context.encounter.author or context.encounter reference cannot be resolved.author and context.encounter references to existing resources.author or Encounter resource.context.encounter by business rule.Guidance
launch/patient context value is a candidate for author when the patient is the author, and the launch/encounter context value is a candidate for context.encounter.Practitioner/123 or Encounter/123. When the author or encounter has no server-side resource to reference, the client includes it as a contained resource and references it by its local id, for example #prac1 or #enc1.Client Requirements
context.period to convey the clinically relevant time period.Guidance
DocumentReference.date is when the DocumentReference was created, not when the content was authored content.attachment.creation is when the attached content was first created. This guidance introduces no other authored-date element.
TODO align with outcome of FHIR-58142.
Client Requirements
identifier with a value that is unique to the document and stays the same if the document is resubmitted.Server Requirements
If-None-Exist).Guidance
Conditional create prevents duplicates only when the client populates identifier. For example: If-None-Exist: identifier=http://example.org/docs|DS-2026-06-30-117.
Duplicate detection protects against network retries and resubmissions of the same document. It doesn't replace the relatesTo replacement mechanism for revised documents.
content.format for additional detail.content.format when provided.Structured formats such as CDA are identified by content.format.
Where does CDA go? Writing Clinical Notes still carries the CDA SHOULD. If this page replaces Writing Clinical Notes, that statement disappears. The proposed structured-document category also implies structured content is in scope. Either add "Servers SHOULD accept application/xml with a CDA content.format code for the clinical-note category," or state explicitly that structured documents are out of scope.
Client Requirements
context.related with a relative reference to the ServiceRequest when the document responds to a solicited request.Guidance
Client Requirements
meta.security with the code PATAST from http://terminology.hl7.org/CodeSystem/v3-ObservationValue when the content is patient-supplied.Server Requirements
PATAST code.PATAST code by policy.Guidance
Patient-supplied content includes both Patient Mediated Write and Patient Generated Write submissions. See the Write Modes Section below for further guidance and an examples. Because servers don't remove the code, it can be relied on to tell where the content came from.
An example of a server policy is adding PATAST to every submission made with a patient/ scope.
Server Requirements
text/plain; charset=utf-8, application/pdf, image/jpeg, or image/png for each supported document type.Guidance
Typical choices are application/pdf for forms and reports, image/jpeg or image/png for photos and scans such as insurance cards, and text/plain; charset=utf-8 for narrative notes.
Server Requirements
content.attachment.data whose decoded content is at least 5 MiB (5,242,880 bytes).content.attachment.url to later readers.content.attachment.url, including content larger than their inline limit.Guidance
The 5 MiB limit applies to the decoded content, matching the meaning of Attachment.size. Base64 encoding adds about 33%, so the request body is larger.
A server that accepts url content retrieves and stores it. Later readers get the server's copy, not the client's link.
This section illustrates the following write submission modes and documents their unique rules and guidance:
Each use case shows the interaction and an example. (Note: The examplesDocumentReference. Attachment data values are truncated placeholders.)
A provider-facing app adds a document to a patient's record at a practitioner's direction. The document is available through the FHIR Server that created it exposing data via its FHIR's RESTful read and search API.
Authorization:
<user|system>/DocumentReference.c, or category-specific version(s) such as <user|system>/DocumentReference.c?category=clinical-note.FHIR RESTful API:
201.DocumentReference Elements:
launch/encounter parameter that an app includes in its SMART authorization request is a candidate value for context.encounter.Example: A cardiologist uses an analytics app launched from the EHR to save a PDF trend report to a patient's record.
# =======TODO: complete this example scenario ==========
resourceType: DocumentReference
identifier:
-
system: 'http://example.org/trendview/reports'
value: rpt-202607-0042
status: current
type:
coding:
-
system: 'http://loinc.org'
code: 70004-7
display: Diagnostic study note
category:
-
coding:
-
system: 'http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category'
code: clinical-note
display: Clinical Note
subject:
reference: Patient/99feede8-2c8c-4135-92d1-083576edc1f8
date: '2026-07-21T15:30:00Z'
author:
-
reference: Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62
display: Dr. Chris Bell
content:
-
attachment:
contentType: application/pdf
data: JVBERi0xLjcK
title: Cardiology trend report - Vanessa Reyes
context:
encounter:
-
reference: Encounter/enc-20260721-7
period:
start: '2021-07-01'
end: '2026-07-21'
A patient-facing app sends a patient-authored document to the patient's provider in response to a provider's request - recorded as a ServiceRequest. The document is available through the FHIR Server that created it exposing data via its FHIR's RESTful read and search API.
Authorization:
patient/DocumentReference.c, or category-specific version(s) such as patient/DocumentReference.c?category=clinical-note.patient/ServiceRequeset.rs.FHIR RESTful API:
ServiceRequest resources with the patient as performer available through read and search .201.ServiceRequest Elements:
ServiceRequest.code provides the specific document type code (either LOINC or local)ServiceRequest.performer is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for this element.ServiceRequest.status to "active" and define the repeat with ServiceRequest.ocurrenceTiming.repeat.DocumentReference Elements:
meta.security = "PATAST".meta.security = "PATAST" by policy (e.g., based on authorization context), even if it is omitted by the client.ServiceRequest in context.related or the FHIR R5 basedOn` extension.meta.security = "PATAST" (Patient asserted).Clients SHALL populate context.related or the FHIR R5 basedOn extension with the active ServiceRequest that requests it.
Document.author is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for authorExample: A provider asks a patient to send weekly activity reports from her fitness tracker, and the patient's app submits each report in response to that request.
# =======TODO: complete this example scenario ==========
resourceType: DocumentReference
meta:
security:
-
system: 'http://terminology.hl7.org/CodeSystem/v3-ObservationValue'
code: PATAST
display: patient asserted
identifier:
-
system: 'http://example.org/fitshare/reports'
value: lin-2026-w29
status: current
type:
coding:
-
system: 'http://loinc.org'
code: 51855-5
display: Patient Note
category:
-
coding:
-
system: 'http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category'
code: medical-history
display: Medical History
subject:
reference: Patient/512cd664-6cd2-4a56-b462-0133464ffaa0
date: '2026-07-21T00:00:00Z'
author:
-
reference: Patient/512cd664-6cd2-4a56-b462-0133464ffaa0
display: Lin Zhang
content:
-
attachment:
contentType: application/pdf
data: JVBERi0xLjcK
title: 'Weekly activity report, July 14-20, 2026'
context:
period:
start: '2026-07-14'
end: '2026-07-20'
related:
-
reference: ServiceRequest/activity-report-weekly
A patient-facing app sends a document to the patient's provider without a specific provider request. The document can patient-generated where the patient authored all or part of the content, or patient-mediated where a patient-facing app, used by the patient or an authorized representative, forwards a document to the patient's provider that someone else authored. Servers commonly treat them the same, and may hold the document for review before it becomes available through read and search.
Business Rules:
Discovery:
Authorization:
patient/DocumentReference.c, or category-specific version(s) such as patient/us-core-documentreference-category|clinical-note.FHIR RESTful API:
201 or 202 depending on documented server policy.DocumentReference Elements:
meta.security = "PATAST".meta.security = "PATAST" by policy (e.g., based on authorization context), even if it is omitted by the client.Clients SHALL include meta.security = "PATAST" (Patient asserted).
Document.author is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for authorExample 1: A patient uses an app to send her advance directive, prepared by her attorney, to her provider as a PDF.
# =======TODO: complete this example scenario ==========
resourceType: DocumentReference
meta:
security:
-
system: 'http://terminology.hl7.org/CodeSystem/v3-ObservationValue'
code: PATAST
display: patient asserted
identifier:
-
system: 'http://example.org/mydirectives/documents'
value: adi-202607-01
status: current
type:
coding:
-
system: 'http://loinc.org'
code: 86533-7
display: Patient Living will
category:
-
coding:
-
system: 'http://loinc.org'
code: 42348-3
display: Advance healthcare directives
subject:
reference: Patient/341912d8-207d-4e73-a3a6-17117e602227
date: '2026-07-21T00:00:00Z'
author:
-
reference: Patient/341912d8-207d-4e73-a3a6-17117e602227
display: Suzie Smith
content:
-
attachment:
contentType: application/pdf
data: JVBERi0xLjcK
title: Advance Healthcare Directive - Suzie Smith
creation: '2026-07-14'
Example 2: Before a checkup, a patient uses his provider's portal app to send a photo of his new insurance card.
# =======TODO: complete this example scenario ==========
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: 64290-0
display: Health insurance card
category:
-
coding:
-
system: 'http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category'
code: insurance-document
display: Insurance Document
subject:
reference: Patient/8da636b7-aaaa-44ab-8ed7-604039829eb6
date: '2026-07-21T00:00:00Z'
author:
-
reference: Patient/8da636b7-aaaa-44ab-8ed7-604039829eb6
display: Mike Jones
content:
-
attachment:
contentType: image/png
data: iVBORw0KGgo=
title: Health Insurance Card - Mike Jones
Example 3 (Patient Mediated Write): A patient forwards a discharge summary from another hospital. The hospital is the author, and the document was written a month before it was sent.
# =======TODO: complete this example scenario ==========
resourceType: DocumentReference
meta:
security:
-
system: 'http://terminology.hl7.org/CodeSystem/v3-ObservationValue'
code: PATAST
display: patient asserted
contained:
-
resourceType: Organization
id: source-org
name: Riverside Community Hospital
-
resourceType: Patient
id: source-patient
name:
-
family: Smith
given:
- Suzanne
birthDate: '1974-03-12'
identifier:
-
system: 'http://riverside.example.org/documents'
value: DS-2026-06-30-117
status: current
type:
coding:
-
system: 'http://loinc.org'
code: 18842-5
display: Discharge summary
category:
-
coding:
-
system: 'http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category'
code: clinical-note
display: Clinical Note
subject:
reference: Patient/341912d8-207d-4e73-a3a6-17117e602227
date: '2026-07-28T09:15:00Z'
author:
-
reference: '#source-org'
display: Riverside Community Hospital
content:
-
attachment:
contentType: application/pdf
data: JVBERi0xLjcK
title: Discharge Summary - Riverside Community Hospital
creation: '2026-06-30'
context:
period:
start: '2026-06-26'
end: '2026-06-30'
sourcePatientInfo:
reference: '#source-patient'
This section establishes client and server rules and guidance for correcting documents after they have been written to a FHIR server. A client can retract a document by changing its status to entered-in-error with the FHIR RESTful patch or update interaction, or supersede it by creating a new DocumentReference that replaces the original. Both mechanisms tell the server and later readers what happened to the document. What a server does next, such as archiving the original or notifying users, is server policy.
Client Requirements
Retraction
patch that changes only status to entered-in-error, or an update that sends the complete resource with only status changed.Replacement
DocumentReference with relatesTo.code = replaces and relatesTo.target referencing the original.relatesTo.target.identifier with the original document's identifier when it has one.Server Requirements
Retraction
status to entered-in-error through patch.status to entered-in-error through update.entered-in-error document through read for authorized requests.entered-in-error documents from search results.Replacement
relatesTo on create and return it unchanged on read and search.Every document needs to answer a few basic questions: who wrote it, when it was created, and where it came from. This section answers them using "small-p" provenance elements in the DocumentReference itself. Although a separate Provenance resource might not be needed for a simple submission, this does not replace it or [US Core Basic Provenance].
This table maps each provenance question to the DocumentReference element that answers it. The example use cases show these elements together.
| Question | Element |
|---|---|
| Who authored the content? | author |
| Who attested to the content? | authenticator, R5 attester cross-version extension |
| Is this patient-asserted? | meta.security = PATAST |
| When was the content created? | content.attachment.creation |
| What period does the content cover? | context.period |
| How does the source system identify the document? | identifier |
| What was this submitted in response to? | context.related |
| What does this supersede? | relatesTo |
| Who is the patient according to the originating system? | context.sourcePatientInfo |
Server Requirements
author with the authenticated client or user.custodian with the receiving organization when they accept a document.DocumentReference.Guidance
custodian on acceptance is one way a server can meet the existing US Core requirement that every DocumentReference have a responsible organization. See Open Question 1 below.author with the submitter would erase the distinction this section exists to preserve.Apps need write permission for DocumentReference. SMART scopes allow access permissions to be delegated to a Client application. Servers can grant SMART v2 scopes for DocumentReference create/update, limit that permission to specific categories, and advertise them in /.well-known/smart-configuration.
Server Requirements
patient/DocumentReference.c scope for Patient Write.user/DocumentReference.c scope for Provider Write.system/DocumentReference.c scope for backend services that write documents..u scopes.scopes_supported in .well-known/smart-configuration.Guidance
.u scope covers both the patch and update interactions used for status correction. See Correction and Replacement.A category-specific scope limits write permission to one category.
Recommended granular scopes
<patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note<patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note<patient|user|system>/DocumentReference.c?category=http://loinc.org|42348-3<patient|user|system>/DocumentReference.u?category=http://loinc.org|42348-3<patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|medical-history<patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|medical-history<patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|insurance-document<patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|insurance-document<patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|identity-document<patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|identity-documentThis table will list every conformance statement on this page, by actor.
Stub. The table will be generated from the conformance statements on this page once the text is stable.
| ID | Actor | Conformance | Requirement | Section |
|---|---|---|---|---|
| TBD | Server | SHALL | TBD | Processing Expectation |
The following items are unresolved.
How to meet US Core's DocumentReference's "responsible-organization requirement"?
The US Core DocumentReference guidance requires that every DocumentReference have a responsible Organization, present either in DocumentReference.custodian or in a Provenance resource targeting the document. For patient-generated and patient-mediated writes there is no responsible organization at the time of submission.
When is discovery needed?
If pre-coordination is required, runtime discovery adds machinery without removing the coordination step.
What about Per-organization discovery versus network-level requirements?
What are the DocumentReference categories candidates?
Is there need for a separate DocumentReference write profile?
Are structured Documents (e.g., CDA and FHIR) in scope?
IG © 2027+ HL7 International / Cross-Group Projects. Package hl7.fhir.us.core#10.0.0-ballot based on FHIR 4.0.1. Generated 2026-11-07
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change