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 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 replaces US Core's Version 9 Clinical Notes guidance page and adopts conventions used in Writing Vital Signs and the Continuous Glucose Monitoring Implementation Guide.
create
$submit-bundle transactionBelow is a glossary of terms used on page.
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 the 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.
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 writes.§Guidance
"Process or review" includes filing an insurance card, 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.
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 (for example, 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 document 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.
Currently, the US Core DocumentReference Category value set contains one concept, clinical-note, and the US Core ADI DocumentReference Profile lists four LOINC codes, including 42348-3 (Advance healthcare directives).
The recommended categories below address 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 DocumentReference.type has a required binding to the US Core DocumentReference Type value set, which is composed of LOINC document types plus the concept "unknown". (the US Core ADI DocumentReference 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 DocumentReference Type value set.
Category LOINC 42348-3 (Advance healthcare directives): Use LOINC codes drawn from the Advance Healthcare Directive Document Types Grouper 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 DocumentReference 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, these LOINC codes might be used:
| 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 or .context.encounter, .reference SHALL be a relative reference to a resource on the Server, or a reference to a contained resource, or a logical reference.§.author or .context.encounter, .display SHOULD be populated.§Server Requirements
author and context.encounter.§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. DocumentReference.content.attachment.creation is when the attached content was first created. This guidance introduces no other authored-date element.
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
identifier. For example: If-None-Exist: identifier=http://example.org/docs|DS-2026-06-30-117.relatesTo replacement mechanism for revised documents.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
Guidance
Patient-supplied content includes both Patient Mediated Write and Patient Generated Write submissions. See the Submission Modes section below for further guidance and 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.
Every rule on this page applies to all three submission modes unless it appears in this table. This table lists only the rules and guidance that differ by mode; the Conformance Requirements tables at the end of the page list every statement in full, one table per actor, with the key cited here.
| Key | Rule | Actor | Provider Write | Solicited Patient Write | Unsolicited Patient Write |
|---|---|---|---|---|---|
| CONF-WD-04, CONF-WD-05 | Response on a successful write | Server | 201 Created |
201 Created |
201 Created or 202 Accepted by documented policy |
| CONF-WD-40, CONF-WD-44 | Make the document available through read and search without further action | Server | SHALL | SHALL | Server policy |
| CONF-WD-50 | Document the review policy for patient submissions | Server | n/a | n/a | SHALL |
| CONF-WD-39 | Support the create scope user/DocumentReference.c or system/DocumentReference.c |
Server | SHALL | n/a | n/a |
| CONF-WD-41, CONF-WD-51, CONF-WD-70 | Support the create scope patient/DocumentReference.c |
Server | n/a | SHALL | SHALL |
| CONF-WD-42 | Support the scope patient/ServiceRequest.rs |
Server | n/a | SHALL | n/a |
| CONF-WD-43 | Make ServiceRequest resources with the patient as performer available through read and search |
Server | n/a | SHALL | n/a |
| CONF-WD-29, CONF-WD-49 | Populate context.related, or the FHIR R5 basedOn extension, with the active ServiceRequest |
Client | n/a | SHALL | n/a |
| CONF-WD-47 | Document whether to populate context.related or the FHIR R5 basedOn extension |
Server | n/a | SHALL | n/a |
| CONF-WD-30, CONF-WD-48, CONF-WD-54 | Include meta.security = PATAST |
Client | n/a | SHALL | SHALL |
| CONF-WD-31, CONF-WD-45, CONF-WD-52 | Do not remove the PATAST code |
Server | n/a | SHALL NOT | SHALL NOT |
| CONF-WD-32, CONF-WD-46, CONF-WD-53 | Add the PATAST code by policy |
Server | n/a | MAY | MAY |
| - | author is the patient, with launch/patient as a candidate value |
Client | n/a | Guidance | Guidance |
| - | launch/encounter is a candidate value for context.encounter |
Client | Guidance | n/a | n/a |
| - | Support the DocumentReference Attestor R5 Extension for document types such as living wills | Server | n/a | n/a | Guidance |
Reading this table
.u scopes are required only of a server that allows status correction or replacement.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.
Scenario
A cardiologist, Dr. Chris Bell, reviews a five-year blood pressure trend report for a patient, Vanessa Reyes, in an analytics app launched from the patient's chart in the EHR. At the cardiologist's direction the app saves the report to the patient's record as a PDF, then searches for it to confirm the write.
The example uses these values:
[base]: https://ehr.example.com/r4Patient/99feede8-2c8c-4135-92d1-083576edc1f8 (Vanessa Reyes)Encounter/enc-20260721-7Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62 (Dr. Chris Bell)http://example.org/trendview/reports, value rpt-202607-0042The app and the EHR established which categories, types, MIME types, and size limits the EHR accepts during integration, so this example includes no runtime discovery step. See Discovery.
Step 1: The EHR launches the app
The cardiologist opens the app from the patient's chart. The EHR invokes the app's registered launch URL with the iss and launch parameters defined by SMART App Launch.
GET https://app.example.com/launch?iss=https%3A%2F%2Fehr.example.com%2Fr4&launch=xyz123
Step 2: The app requests authorization
The app asks for the scopes it needs, including the create scope for DocumentReference. Parameter values are shown unencoded for readability.
GET https://ehr.example.com/auth/authorize?
response_type=code&
client_id=trendview-app&
redirect_uri=https://app.example.com/redirect&
launch=xyz123&
aud=https://ehr.example.com/r4&
scope=launch openid fhirUser user/DocumentReference.crs user/Patient.rs user/Encounter.rs&
state=98wrghuwuogerg2&
code_challenge=DJsz...&
code_challenge_method=S256
user/DocumentReference.crs combines the create permission this guidance requires of the server for Provider Write§ with the read and search permissions the app needs for Steps 4 and 7. A category-specific scope such as user/DocumentReference.crs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note can be used in its place. See SMART Scopes.
Step 3: The EHR returns an access token with patient and encounter context
The app exchanges the authorization code at the token endpoint.
POST https://ehr.example.com/auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=5a8b...&redirect_uri=https%3A%2F%2Fapp.example.com%2Fredirect&client_id=trendview-app&code_verifier=erw3...
Response
HTTP/1.1 200 OK
Content-Type: application/json
[other headers]
Response body
{
"access_token": "i8hweunweunweofiwweoijewiwe",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "launch openid fhirUser user/DocumentReference.crs user/Patient.rs user/Encounter.rs",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"patient": "99feede8-2c8c-4135-92d1-083576edc1f8",
"encounter": "enc-20260721-7"
}
The EHR launch supplies the context the app writes with, so the app does not prompt the cardiologist to select a patient or an encounter:
patient is the id the app uses for subject.encounter is the id the app uses for context.encounter. It is a candidate value only; a document that belongs to no encounter omits the element.fhirUser in the id_token resolves to Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62, the id the app uses for author.Step 4: The app reads the patient and encounter context
The app reads both context resources to confirm the chart it was launched against and to populate the display values this guidance recommends on author and context.encounter.§ Responses are abbreviated to the elements the app uses.
GET [base]/Patient/99feede8-2c8c-4135-92d1-083576edc1f8
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Accept: application/fhir+json
Response body
{
"resourceType": "Patient",
"id": "99feede8-2c8c-4135-92d1-083576edc1f8",
"name": [
{
"family": "Reyes",
"given": ["Vanessa"]
}
],
"gender": "female",
"birthDate": "1962-03-14"
}
GET [base]/Encounter/enc-20260721-7
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Accept: application/fhir+json
Response body
{
"resourceType": "Encounter",
"id": "enc-20260721-7",
"status": "in-progress",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "AMB",
"display": "ambulatory"
},
"type": [
{
"text": "Cardiology office visit"
}
],
"subject": {
"reference": "Patient/99feede8-2c8c-4135-92d1-083576edc1f8"
},
"period": {
"start": "2026-07-21T15:00:00Z"
}
}
Note that context.period carries the clinically relevant period of the report content, not the encounter period.§ Here that is the five-year span of the trend data, while the encounter is the visit at which the report was reviewed.
Step 5: The app writes the document
The app submits the report with FHIR RESTful create. If-None-Exist makes the write idempotent against a network retry, using the identifier the app assigns to the document.§§
POST [base]/DocumentReference
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://example.org/trendview/reports|rpt-202607-0042
Request body
The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.
{
"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",
"display": "Vanessa Reyes"
},
"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",
"creation": "2026-07-21"
}
}
],
"context": {
"encounter": [
{
"reference": "Encounter/enc-20260721-7",
"display": "Cardiology office visit, 2026-07-21"
}
],
"period": {
"start": "2021-07-01",
"end": "2026-07-21"
}
}
}
Every value in the submission comes from the launch context or from the report itself: subject and author from Step 3, their display values and the encounter display from Step 4, date from the moment of submission, and attachment.creation from when the app generated the PDF.
Step 6: The EHR accepts the document
A Provider Write is always solicited, so the response is 201 Created with a Location header and the document is available through read and search without further action.§§ The ETag and Last-Modified headers are not required by this page; base FHIR asks a server to return them on a create when it supports versioning.
HTTP/1.1 201 Created
Location: https://ehr.example.com/r4/DocumentReference/doc-rpt-202607-0042/_history/1
ETag: W/"1"
Last-Modified: Tue, 21 Jul 2026 15:30:04 GMT
[other headers]
The response body is the created resource. As base FHIR requires of a create, the EHR populated id, meta.versionId, and meta.lastUpdated. It also stamped meta.profile with the US Core DocumentReference profile and preserved the submitted codings as received.§
In this example the EHR also sets custodian to the organization responsible for the record. Nothing on this page requires that; see Open Questions.
The submission carries no meta.security code of PATAST: the content is provider-supplied, not patient-asserted. See Patient-asserted Signaling.
Step 7: The app searches for the document
The app confirms the write with a search that the US Core DocumentReference Profile Quick Start requires servers to support.
GET [base]/DocumentReference?patient=99feede8-2c8c-4135-92d1-083576edc1f8&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Accept: application/fhir+json
Response
HTTP/1.1 200 OK
Content-Type: application/fhir+json
[other headers]
Response body
The new report is in the search set. Earlier notes for the patient are omitted here, and the matched resource is abbreviated.
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://ehr.example.com/r4/DocumentReference?patient=99feede8-2c8c-4135-92d1-083576edc1f8&category=http%3A%2F%2Fhl7.org%2Ffhir%2Fus%2Fcore%2FCodeSystem%2Fus-core-documentreference-category%7Cclinical-note"
}
],
"entry": [
{
"fullUrl": "https://ehr.example.com/r4/DocumentReference/doc-rpt-202607-0042",
"resource": {
"resourceType": "DocumentReference",
"id": "doc-rpt-202607-0042",
"status": "current",
"subject": {
"reference": "Patient/99feede8-2c8c-4135-92d1-083576edc1f8"
},
"date": "2026-07-21T15:30:00Z",
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "/Binary/doc-rpt-202607-0042-pdf",
"title": "Cardiology trend report - Vanessa Reyes"
}
}
]
},
"search": {
"mode": "match"
}
}
]
}
The EHR returns the attachment it stored as a url to a Binary resource rather than inline, which is its choice on read and is not governed by this page. The report is also available to the care team in the patient's chart.
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/ServiceRequest.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 LOINC or local type code.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.occurrenceTiming.repeat.DocumentReference Elements:
meta.security = "PATAST".§meta.security = "PATAST" by policy (for example, 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.§
DocumentReference.author is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for this element.Example: 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.
Scenario
A cardiologist asks a patient, Lin Zhang, to send a weekly activity report from her fitness tracker. The clinician records the request in the EHR as a standing ServiceRequest with the patient as performer. Each week the patient's fitness app finds that request, submits the week's report against it, and confirms the write.
The example uses these values:
[base]: https://provider.example.com/r4Patient/512cd664-6cd2-4a56-b462-0133464ffaa0 (Lin Zhang)ServiceRequest/activity-report-weeklyhttp://example.org/fitshare/reports, value lin-2026-w29Authorization
The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for both subject and author, because for a patient write the patient is the author. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:
patient/DocumentReference.c to write the report§patient/ServiceRequest.rs to find the request it responds to§offline_access, so next week's report needs no new sign-inStep 1: The app finds the request it is responding to
The server makes ServiceRequest resources with the patient as performer available through read and search.§
GET [base]/ServiceRequest?patient=512cd664-6cd2-4a56-b462-0133464ffaa0&status=active
Authorization: Bearer j4kfhw84hf8w4hf8w4hf8w4h
Accept: application/fhir+json
Response body
The search set holds one active request. The resource is abbreviated to the elements the app uses.
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"entry": [
{
"fullUrl": "https://provider.example.com/r4/ServiceRequest/activity-report-weekly",
"resource": {
"resourceType": "ServiceRequest",
"id": "activity-report-weekly",
"status": "active",
"intent": "order",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "51855-5",
"display": "Patient Note"
}
],
"text": "Weekly activity report from fitness tracker"
},
"subject": {
"reference": "Patient/512cd664-6cd2-4a56-b462-0133464ffaa0"
},
"performer": [
{
"reference": "Patient/512cd664-6cd2-4a56-b462-0133464ffaa0",
"display": "Lin Zhang"
}
],
"requester": {
"reference": "Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62",
"display": "Dr. Chris Bell"
},
"authoredOn": "2026-06-15",
"occurrenceTiming": {
"repeat": {
"frequency": 1,
"period": 1,
"periodUnit": "wk"
}
}
},
"search": {
"mode": "match"
}
}
]
}
The request tells the app three things: that it is still active and so still expects reports, that occurrenceTiming.repeat makes it a standing weekly order rather than a one-time request, and that code is the document type to submit.
Step 2: The app writes the report
POST [base]/DocumentReference
Authorization: Bearer j4kfhw84hf8w4hf8w4hf8w4h
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://example.org/fitshare/reports|lin-2026-w29
Request body
The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.
{
"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",
"display": "Lin Zhang"
},
"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",
"creation": "2026-07-21"
}
}
],
"context": {
"period": {
"start": "2026-07-14",
"end": "2026-07-20"
},
"related": [
{
"reference": "ServiceRequest/activity-report-weekly"
}
]
}
}
Three elements make this a solicited submission rather than an unsolicited one:
context.related points at the active ServiceRequest found in Step 1.§ The server documents whether to use this element or the FHIR R5 basedOn extension.§meta.security carries PATAST, because the content is patient-supplied.§ The server does not remove it,§ so a later reader can tell where the content came from.author is the patient, taken from the patient context value in the token response.context.period is the week the activity was recorded, not the moment of submission.§ date is when the app created the DocumentReference, and attachment.creation is when it generated the PDF. The identifier carries the week number, so next week's report gets its own identifier and If-None-Exist suppresses only a retry of this one.§
Step 3: The server accepts the report
A solicited submission answers a request the provider already made, so it is accepted and filed without review. The response is 201 Created.§
HTTP/1.1 201 Created
Location: https://provider.example.com/r4/DocumentReference/doc-lin-2026-w29/_history/1
ETag: W/"1"
Last-Modified: Tue, 21 Jul 2026 00:04:12 GMT
[other headers]
The response body is the created resource, with id, meta.versionId, and meta.lastUpdated populated as base FHIR requires of a create. The server also stamped meta.profile with the US Core DocumentReference profile, preserved the submitted codings as received,§ and left meta.security in place, so the PATAST code is still on the stored resource.§
Reads and searches
The report is available through read and search immediately, with no further action by the patient or the provider.§ A confirmation search takes the same form as the one in the Provider Write example, and the returned DocumentReference keeps the context.related reference, which ties the report back to the order for the clinician who asked for it.
Next week the app repeats these steps with a new identifier and a new context.period, against the same standing ServiceRequest.
A patient-facing app sends a document to the patient's provider without a specific provider request. The document can be 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 might 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 (for example, based on authorization context), even if it is omitted by the client.Clients SHALL include meta.security = "PATAST" (Patient asserted).
DocumentReference.author is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for this element.Example 1: A patient uses an app to send her advance directive, prepared by her attorney, to her provider as a PDF.
Scenario
A patient, Suzie Smith, has an advance healthcare directive her attorney prepared. No provider asked for it. She uses an app to check which directive types her provider accepts, then sends the signed PDF. The provider holds patient submissions for staff review before filing them, so the document is not readable or searchable on return.
The example uses these values:
[base]: https://provider.example.com/r4Patient/341912d8-207d-4e73-a3a6-17117e602227 (Suzie Smith)http://example.org/mydirectives/documents, value adi-202607-01Authorization
The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for both subject and author. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:
patient/DocumentReference.c?category=http://loinc.org|42348-3 to write the directive, and the matching .rs for the read-back. These are category-specific scopes rather than the unrestricted patient/DocumentReference.c, so the grant covers advance healthcare directives and nothing else.§ A server that supports only the unrestricted scope grants that instead. See SMART Scopes.Step 1: The app discovers which directive types the server accepts
A patient-facing app cannot negotiate its capabilities with every provider in advance, so runtime discovery matters here in a way it does not for a provider-facing app. The app expands the type value set in the incoming direction to learn what this server accepts on write.§
GET [base]/ValueSet/$expand?context=http://hl7.org/fhir/us/core/StructureDefinition/us-core-adi-documentreference#DocumentReference.type&contextDirection=incoming
Authorization: Bearer k2mfy37dhs8dj3kfhw8s
Accept: application/fhir+json
Response body
{
"resourceType": "ValueSet",
"status": "active",
"expansion": {
"timestamp": "2026-07-21T14:02:11Z",
"parameter": [
{
"name": "context",
"valueString": "DocumentReference.type"
},
{
"name": "contextDirection",
"valueString": "incoming"
}
],
"contains": [
{
"system": "http://loinc.org",
"code": "86533-7",
"display": "Patient Living will"
},
{
"system": "http://loinc.org",
"code": "84095-9",
"display": "Do not resuscitate"
},
{
"system": "http://loinc.org",
"code": "93037-0",
"display": "Portable medical order form"
}
]
}
}
The living will code the patient selected, 86533-7, is in the expansion, so the app proceeds. The server's published API documentation covers the same ground for implementers who cannot call $expand, including the MIME types it accepts, its size limits, and its review policy for patient submissions.§§
Step 2: The app writes the directive
POST [base]/DocumentReference
Authorization: Bearer k2mfy37dhs8dj3kfhw8s
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://example.org/mydirectives/documents|adi-202607-01
Request body
The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.
{
"resourceType": "DocumentReference",
"meta": {
"security": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code": "PATAST",
"display": "patient asserted"
}
]
},
"extension": [
{
"url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-DocumentReference.attester",
"extension": [
{
"url": "mode",
"valueCodeableConcept": {
"coding": [
{
"system": "http://hl7.org/fhir/composition-attestation-mode",
"code": "personal"
}
]
}
},
{
"url": "time",
"valueDateTime": "2026-07-14T10:30:00Z"
},
{
"url": "party",
"valueReference": {
"reference": "Patient/341912d8-207d-4e73-a3a6-17117e602227",
"display": "Suzie Smith"
}
}
]
}
],
"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",
"display": "Suzie Smith"
},
"date": "2026-07-21T14:05: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"
}
}
]
}
meta.security carries PATAST, because the content is patient-supplied.§ The server does not remove it,§ so a later reader can tell the directive arrived from the patient.
author is the patient even though her attorney drafted the document, because the patient is the party who asserts it. The optional DocumentReference Attestor R5 Extension records who signed it and when, which this guidance offers as a candidate for document types such as living wills. The attestation time and attachment.creation are the day she signed, a week before she sent it; date is the moment of submission.§ There is no context.encounter: the directive belongs to no visit.
Step 3: The server accepts the directive for review
The provider's documented policy is to route unsolicited patient submissions to a staff review queue, so the response is 202 Accepted rather than 201 Created.§
HTTP/1.1 202 Accepted
Content-Type: application/fhir+json
[other headers]
Response body
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Document received and queued for review by health information management. It will appear in the patient's record once accepted."
}
]
}
There is no Location header, because there is no resource to read yet. This page requires an OperationOutcome only on a failed write,§ so returning one here to explain the hold is this server's choice. A 202 is possible only for an unsolicited patient submission; a Provider Write and a Solicited Patient Write are both answered 201.
Step 4: A search does not find the document yet
GET [base]/DocumentReference?patient=341912d8-207d-4e73-a3a6-17117e602227&category=http://loinc.org|42348-3
Authorization: Bearer k2mfy37dhs8dj3kfhw8s
Accept: application/fhir+json
Response body
{
"resourceType": "Bundle",
"type": "searchset",
"total": 0,
"entry": []
}
Availability through read and search is server policy for an unsolicited submission, which is why the server has to document that policy.§ An app that treats a 202 as "filed" and polls for the document will keep finding nothing until review completes, so a 202 is better surfaced to the patient as submitted and pending. Once staff accept the directive the server files it, and the same search returns it.
Example 2: Before a checkup, a patient uses his provider's portal app to send a photo of his new insurance card.
Scenario
Before a checkup, a patient, Mike Jones, photographs his new insurance card in his provider's patient portal app and sends it. No provider asked for it, so the submission is unsolicited. The provider's documented policy is to file insurance documents on arrival and let registration staff work them from the chart, so the response is 201 Created rather than 202 Accepted.
The example uses these values:
[base]: https://provider.example.com/r4Patient/8da636b7-aaaa-44ab-8ed7-604039829eb6 (Mike Jones)Authorization
The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for both subject and author. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:
patient/DocumentReference.c to write the card, and .rs for the read-back. A server that supports a category-specific scope can restrict the grant to insurance documents instead, with patient/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|insurance-document.§The portal app is the provider's own, so the categories, types, MIME types, and size limits were settled during integration and the app needs no runtime discovery.
Step 1: The app writes the document
POST [base]/DocumentReference
Authorization: Bearer p9sdkfj39sdkfj39sdkfj
Content-Type: application/fhir+json
Accept: application/fhir+json
Request body
The content.attachment.data value below is a truncated placeholder for the base64 encoded PNG.
{
"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",
"display": "Mike Jones"
},
"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"
}
}
]
}
A photograph is not a narrative document, so the submission differs from the other examples in three ways:
contentType is image/png. A server supporting the insurance-document category accepts at least one of text/plain; charset=utf-8, application/pdf, image/jpeg, or image/png for it, and documents which.§§ A phone photograph can exceed the 5 MiB a server is required to accept inline, so an app either downscales it or uses a server that accepts content by url.§§context.period. The card has no clinically relevant period, and the checkup it was sent ahead of has not happened, so there is no encounter to reference either.identifier, so If-None-Exist is not available and a retried submission can produce a second copy. Populating one that stays stable across resubmission is the way to prevent that.§meta.security still carries PATAST, as it does for every patient submission.§
Step 2: The server accepts the document
HTTP/1.1 201 Created
Location: https://provider.example.com/r4/DocumentReference/doc-ins-88213/_history/1
ETag: W/"1"
Last-Modified: Tue, 21 Jul 2026 00:02:38 GMT
[other headers]
The 201 reflects this server's documented policy for the insurance-document category, not a rule of this page. The same server holds clinical notes from patients for review and answers those 202. Either response is conformant for an unsolicited submission as long as the policy is documented.§§§
Reads and searches
The 201 means the card is on file before the patient arrives, so a confirmation search of the form shown in the Provider Write example returns it right away and the app can show him it was received. Registration staff work it from the chart.
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.
Scenario
A patient, Suzie Smith, was discharged from another hospital a month ago. She retrieves the discharge summary from that hospital's patient portal and forwards it to her own provider through her app. The hospital, not the patient, authored the document, and it was written a month before she sent it. The provider holds it for clinician review before it joins the chart.
This is a patient-mediated write: the patient is the submitter but not the author. How the app obtained the document from the other hospital is out of scope for this page.
The example uses these values:
[base]: https://provider.example.com/r4Patient/341912d8-207d-4e73-a3a6-17117e602227 (Suzie Smith, as known to the receiving provider)http://riverside.example.org/documents, value DS-2026-06-30-117Authorization
The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for subject only. Unlike the other patient examples it is not used for author, because the patient did not write this document. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:
patient/DocumentReference.c, the unrestricted create scope, because a forwarded document can be of any category the server acceptsStep 1: The app forwards the discharge summary
POST [base]/DocumentReference
Authorization: Bearer t5hwkd93jfksl20dmfk3
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://riverside.example.org/documents|DS-2026-06-30-117
Request body
The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.
{
"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",
"display": "Suzie Smith"
},
"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"
}
}
}
What makes this submission different from a patient-generated one:
author is the authoring hospital, carried as a contained Organization and referenced by its local id #source-org. The receiving server has no Organization resource for Riverside, so there is no relative reference to give. A server accepts a contained reference,§ might persist its content,§ and does not reject the submission just because the reference does not resolve to one of its own resources.§context.sourcePatientInfo holds the demographics the other hospital had on file, as a second contained resource. That lets a reviewer confirm the forwarded document is about this patient.meta.security carries PATAST even though a hospital wrote the content.§ The code says the submission came through the patient, which is what a later reader needs to know; it does not claim the patient authored it.Three dates carry three different meanings here, and only creation describes the document itself:§
| Element | Value | Meaning |
|---|---|---|
context.period |
2026-06-26 to 2026-06-30 | the hospital stay the summary covers |
attachment.creation |
2026-06-30 | the day the hospital wrote the summary |
date |
2026-07-28 | the moment the app submitted it, a month later |
Step 2: The server accepts the document for review
HTTP/1.1 202 Accepted
Content-Type: application/fhir+json
[other headers]
Response body
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Document received and routed to the care team for review before it is added to the chart."
}
]
}
An outside document asserts clinical facts a clinician has not seen, so this server reviews it rather than filing it on arrival. The response carries no Location header: nothing is readable yet. Availability through read and search is server policy for an unsolicited submission, and the server documents that policy.§
Reads and searches
A clinician reviews the summary and accepts it, and the server files it. Until then a search finds nothing, as shown in Example 1 of Unsolicited Patient Write above. Once filed, two things the app submitted are still on the stored resource: the PATAST code, which the server does not remove,§ so every later reader can tell the document arrived through the patient rather than from the authoring hospital directly; and the identifier the hospital assigned, so if the patient forwards the same summary again, or the hospital later sends it directly, the server has something to match on.§
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 section 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 create/update scopes for DocumentReference or category-specific scopes, and advertise them in /.well-known/smart-configuration.
Server Requirements
patient/DocumentReference.c or category-specific scopes for Patient Write.§user/DocumentReference.c or category-specific scopes for Provider Write.§system/DocumentReference.c or category-specific scopes 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 Corrections and Replacements.A category-specific scope limits write permission to one category.
Recommended category-specific 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-documentThe two tables below list every conformance statement on this page, one table per actor. Each statement is footnoted where it is written on the page with a § marker linking to its row here.
Legend
CONF-WD-NN. It is the anchor target of the § footnote marker that follows the statement where it is written on this page.ALL applies to every submission mode. PROV Provider Write, SPAT Solicited Patient Write, UPAT Unsolicited Patient Write, PAT both patient modes. A statement in a general section is ALL unless it is scoped tighter.| Key | Mode | Conformance | Conditional | Requirement | Section |
|---|---|---|---|---|---|
| CONF-WD-09 | ALL | SHALL | - | Clients SHALL populate at least one |
Document Type and Category |
| CONF-WD-15 | ALL | SHALL | ✔ | Clients SHALL be capable of populating |
References: Author and Context.encounter |
| CONF-WD-16 | ALL | SHALL | ✔ | When a Client populates |
References: Author and Context.encounter |
| CONF-WD-17 | ALL | SHOULD | ✔ | When a Client populates |
References: Author and Context.encounter |
| CONF-WD-23 | ALL | SHALL | - | Clients SHALL use |
Date Handling |
| CONF-WD-24 | ALL | SHOULD | - | Clients SHOULD populate |
Identifier |
| CONF-WD-29 | ALL | SHALL | ✔ | Clients SHALL populate |
Context.related |
| CONF-WD-30 | PAT | SHALL | ✔ | Clients SHALL include |
Patient-asserted Signaling |
| CONF-WD-48 | SPAT | SHALL | - | Clients SHALL include |
Solicited Patient Write |
| CONF-WD-49 | SPAT | SHALL | - | Clients SHALL populate |
Solicited Patient Write |
| CONF-WD-54 | UPAT | SHALL | - | Clients SHALL include |
Unsolicited Patient Write |
| CONF-WD-55 | ALL | SHALL | ✔ | To mark a document as entered in error, clients SHALL use either a |
Corrections and Replacements |
| CONF-WD-56 | ALL | SHOULD | ✔ | To supersede a document, clients SHOULD create a new |
Corrections and Replacements |
| CONF-WD-57 | ALL | SHALL | - | A replacing document SHALL contain the complete revised content, not only the changes. |
Corrections and Replacements |
| CONF-WD-58 | ALL | SHOULD | ✔ | Clients SHOULD also populate |
Corrections and Replacements |
| Key | Mode | Conformance | Conditional | Requirement | Section |
|---|---|---|---|---|---|
| CONF-WD-01 | ALL | SHALL | - | Servers SHALL support |
Processing Expectation |
| CONF-WD-02 | ALL | SHALL | - | Servers SHALL only accept documents that the organization can and intends to process or review. |
Processing Expectation |
| CONF-WD-03 | ALL | SHALL NOT | - | Servers SHALL NOT document support for a |
Processing Expectation |
| CONF-WD-04 | ALL | SHALL | ✔ | Servers SHALL respond |
Processing Expectation |
| CONF-WD-05 | ALL | SHALL | ✔ | Servers SHALL respond |
Processing Expectation |
| CONF-WD-06 | ALL | SHOULD | - | Servers SHOULD return an |
Processing Expectation |
| CONF-WD-07 | ALL | SHALL | - | Servers SHALL publish API documentation covering supported categories and types, MIME types, size limits, |
Discovery |
| CONF-WD-08 | ALL | SHOULD | - | Servers SHOULD support |
Discovery |
| CONF-WD-10 | ALL | SHALL | - | Servers SHALL publish API documentation covering supported categories and types. |
Document Type and Category |
| CONF-WD-11 | ALL | SHALL | - | Servers SHALL support at least one category. |
Document Type and Category |
| CONF-WD-12 | ALL | SHALL NOT | ✔ | Servers SHALL NOT reject a submission with unsupported category codes if it contains at least one category code (as a repeating element) they support. |
Document Type and Category |
| CONF-WD-13 | ALL | SHALL NOT | ✔ | Servers SHALL NOT reject a submission with unsupported type codes if it contains at least one code translation they support. |
Document Type and Category |
| CONF-WD-14 | ALL | SHOULD | - | Servers SHOULD preserve the submitted coding(s) as received. |
Document Type and Category |
| CONF-WD-18 | ALL | SHALL | - | Servers SHALL accept both relative references to resources on the server and references to contained resources for |
References: Author and Context.encounter |
| CONF-WD-19 | ALL | SHALL NOT | - | Servers SHALL NOT reject a submission solely because an |
References: Author and Context.encounter |
| CONF-WD-20 | ALL | SHOULD | - | Servers SHOULD attempt to match |
References: Author and Context.encounter |
| CONF-WD-21 | ALL | MAY | - | Servers MAY persist the content of a contained |
References: Author and Context.encounter |
| CONF-WD-22 | ALL | MAY | - | Servers MAY require |
References: Author and Context.encounter |
| CONF-WD-25 | ALL | SHOULD | - | Servers SHOULD support conditional create ( |
Identifier |
| CONF-WD-26 | ALL | MAY | - | Servers MAY detect duplicates using identifiers, hashes, or other methods. |
Identifier |
| CONF-WD-31 | PAT | SHALL NOT | - | Servers SHALL NOT remove the |
Patient-asserted Signaling |
| CONF-WD-32 | PAT | MAY | - | Servers MAY add the |
Patient-asserted Signaling |
| CONF-WD-33 | ALL | SHALL | - | Servers SHALL accept at least one of |
MIME Support |
| CONF-WD-34 | ALL | SHALL | - | Servers SHALL document the MIME types they accept for each supported document type. |
MIME Support |
| CONF-WD-35 | ALL | SHALL | - | Servers SHALL accept inline |
Size Limits |
| CONF-WD-36 | ALL | SHALL | - | Servers SHALL document their attachment size limits. |
Size Limits |
| CONF-WD-37 | ALL | SHALL NOT | - | Servers SHALL NOT expose a client-supplied |
Size Limits |
| CONF-WD-38 | ALL | MAY | - | Servers MAY accept content by |
Size Limits |
| CONF-WD-39 | PROV | SHALL | - | Scopes: servers SHALL support FHIR RESTful create using |
Provider Write |
| CONF-WD-40 | PROV | SHALL | - | Servers SHALL make the document available through read and search without further action. The response is always |
Provider Write |
| CONF-WD-41 | SPAT | SHALL | - | Scopes: servers SHALL support |
Solicited Patient Write |
| CONF-WD-42 | SPAT | SHALL | - | Scopes: servers SHALL support |
Solicited Patient Write |
| CONF-WD-43 | SPAT | SHALL | - | Servers SHALL make the |
Solicited Patient Write |
| CONF-WD-44 | SPAT | SHALL | - | Servers SHALL make the document available through read and search without further action. The response is |
Solicited Patient Write |
| CONF-WD-45 | SPAT | SHALL NOT | - | Servers SHALL NOT remove |
Solicited Patient Write |
| CONF-WD-46 | SPAT | MAY | ✔ | Servers MAY add |
Solicited Patient Write |
| CONF-WD-47 | SPAT | SHALL | - | Servers SHALL document whether to populate the active |
Solicited Patient Write |
| CONF-WD-50 | UPAT | SHALL | - | Servers SHALL document their review policy for patient submissions. |
Unsolicited Patient Write |
| CONF-WD-51 | UPAT | SHALL | - | Scopes: servers SHALL support |
Unsolicited Patient Write |
| CONF-WD-52 | UPAT | SHALL NOT | - | Servers SHALL NOT remove |
Unsolicited Patient Write |
| CONF-WD-53 | UPAT | MAY | ✔ | Servers MAY add |
Unsolicited Patient Write |
| CONF-WD-59 | ALL | SHOULD | - | Servers SHOULD allow the submitting client to change |
Corrections and Replacements |
| CONF-WD-60 | ALL | MAY | - | Servers MAY allow the submitting client to change |
Corrections and Replacements |
| CONF-WD-61 | ALL | SHALL | - | Servers SHALL continue to return an |
Corrections and Replacements |
| CONF-WD-62 | ALL | MAY | - | Servers MAY exclude |
Corrections and Replacements |
| CONF-WD-63 | ALL | SHALL | - | Servers SHALL accept |
Corrections and Replacements |
| CONF-WD-64 | ALL | MAY | - | Servers MAY ignore the replacement relationship in their own processing. |
Corrections and Replacements |
| CONF-WD-65 | ALL | SHALL | - | Servers SHALL persist the submitted Provenance-bearing elements, and return them unchanged on read and search, including elements they don't otherwise process. |
Provenance-bearing Elements |
| CONF-WD-66 | ALL | SHALL NOT | - | Servers SHALL NOT reject a submission solely because a provenance element is absent or cannot be resolved. |
Provenance-bearing Elements |
| CONF-WD-67 | ALL | SHALL NOT | - | Servers SHALL NOT replace a client-supplied |
Provenance-bearing Elements |
| CONF-WD-68 | ALL | MAY | ✔ | Servers MAY populate |
Provenance-bearing Elements |
| CONF-WD-69 | ALL | MAY | - | Servers MAY create a US Core Provenance Profile resource targeting the created |
Provenance-bearing Elements |
| CONF-WD-70 | ALL | SHALL | - | Servers SHALL support the |
SMART Scopes |
| CONF-WD-71 | ALL | SHALL | - | Servers SHALL support the |
SMART Scopes |
| CONF-WD-72 | ALL | SHALL | - | Servers SHALL support the |
SMART Scopes |
| CONF-WD-73 | ALL | SHALL | ✔ | Servers that allow status correction or replacement SHALL support the matching |
SMART Scopes |
| CONF-WD-74 | ALL | SHALL | - | Servers SHALL list their supported scopes in |
SMART Scopes |
| CONF-WD-75 | ALL | SHOULD | - | Servers SHOULD accept logical references for |
References: Author and Context.encounter |
The following items are unresolved.
How to meet US Core's DocumentReference "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 a need for a separate DocumentReference write profile?