This page is part of the US Core (v3.1.0: STU3) based on FHIR R4. The current version which supercedes this version is 5.0.1. For a full list of available versions, see the Directory of published versions
StructureDefinition-us-core-documentreference
This profile sets minimum expectations for searching and fetching fetching patient documents including Clinical Notes using the DocumentReference resource. It identifies the mandatory core elements, extensions, vocabularies and value sets which SHALL be present in the DocumentReference resource when using this profile. Prior to reviewing this profile, implementers are encouraged to read the Clinical Notes Guidance to understand the overlap of US Core DocumentReference Profile and US Core DiagnosticReport Profile for Report and Note exchange.
Example Usage Scenarios:
The following are example usage scenarios for the US Core DocumentReference profile. See the Clinical Notes Guidance section for additional detail on using this profile for Clinical Notes:
- Query for all documents belonging to a Patient
- Query for a specific Clinical Note type (e.g. Discharge Summary or Continuity of Care Document (CCD))
- Query for all Clinical Notes belonging to a Patient
- Write a new Note to a Patient’s Chart
Mandatory and Must Support Data Elements
The following data-elements are mandatory (i.e data MUST be present) or must be supported if the data is present in the sending system (Must Support definition). They are presented below in a simple human-readable explanation. Profile specific guidance and examples are provided as well. The Formal Profile Definition below provides the formal summary, definitions, and terminology requirements.
Each DocumentReference must have:
- a status
- a document category
- a code describing the type of document
- a patient
- the MIME type (i.e. contentType) of the document
- an address (e.g. url) where the document can be retrieved or the content as inline base64 encoded data
Each DocumentReference must support:
- a business identifier for the DocumentReference (possibly generated by the transcription system or EHR)
- date and time the reference was created
- an author
- the organization responsible for the document, referred to as custodian.
- a code identifying the specific details about the format of the document — over and above the content’s MIME type
- the patient encounter that is being referenced
- clinically relevant date
Profile specific implementation guidance:
- See Clinical Notes Guidance
- The
DocumentReference.type
binding must support at a minimum the 5 Common Clinical Notes and may extend to the full US Core DocumentReference Type Value Set - For a C-CDA Clinical Summary of Care (CCD):
- The document type code is the LOINC code 34133-9 Summary of episode note.
- The format code is
urn:hl7-org:sdwg:ccda-structuredBody:2.1
- The
content.url
may refer to a FHIR Binary Resource (i.e. [base]/Binary/[id]), FHIR Document Bundle (i.e [base]/Bundle/[id] or other endpoint.
Examples
- DocumentReference-episode-summary Retrieve a URL for an episode summary note (CCD).
Formal Views of Profile Content
Description of Profiles, Differentials, and Snapshots.
The official URL for this profile is:
http://hl7.org/fhir/us/core/StructureDefinition/us-core-documentreference
Published on Sun Aug 11 00:00:00 AEST 2019 as active by the HL7 US Realm Steering Committee.
This profile builds on DocumentReference
DocumentReference
Summary of the Mandatory Requirements
- A code in
DocumentReference.status
with a required binding to DocumentReferenceStatus - A CodeableConcept in
DocumentReference.type
with a required binding to US Core DocumentReference Type - One or more CodeableConcepts in
DocumentReference.category
with an extensible binding to US Core DocumentReference Category - A Patient Reference in
DocumentReference.subject
- A Content in
DocumentReference.content
- which must have a Attachment value in
DocumentReference.content.attachment
- which should have a Coding value in
DocumentReference.content.format
with an extensible binding to DocumentReference Format Code Set
- which must have a Attachment value in
Summary of the Must Support Requirements
- One or more Identifiers in
DocumentReference.identifier
- An instant in
DocumentReference.date
- One or more Author References in
DocumentReference.author
- A Custodian Reference in
DocumentReference.custodian
- A Context in
DocumentReference.context
- which should have a Encounter Reference value in
DocumentReference.context.encounter
- which should have a Period value in
DocumentReference.context.period
- which should have a Encounter Reference value in
Summary of Constraints
- DocumentReference.content.attachment.url or DocumentReference.content.attachment.data or both SHALL be present.
Name | Flags | Card. | Type | Description & Constraints |
---|---|---|---|---|
DocumentReference | I | 0..* | A reference to a document | |
id | Σ | 0..1 | string | Logical id of this artifact |
meta | ΣI | 0..1 | Meta | Metadata about the resource |
implicitRules | ?!ΣI | 0..1 | uri | A set of rules under which this content was created |
language | I | 0..1 | code | Language of the resource content Binding: CommonLanguages (preferred) Max Binding: AllLanguages |
text | I | 0..1 | Narrative | Text summary of the resource, for human interpretation |
contained | 0..* | Resource | Contained, inline Resources | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!I | 0..* | Extension | Extensions that cannot be ignored |
masterIdentifier | ΣI | 0..1 | Identifier | Master Version Specific Identifier |
identifier | SΣI | 0..* | Identifier | Other identifiers for the document |
status | ?!SΣI | 1..1 | code | current | superseded | entered-in-error Binding: DocumentReferenceStatus (required) |
docStatus | ΣI | 0..1 | code | preliminary | final | amended | entered-in-error Binding: CompositionStatus (required) |
type | SΣI | 1..1 | CodeableConcept | Kind of document (LOINC if possible) Binding: US Core DocumentReference Type (required) Min Binding: US Core Clinical Note Type |
category | SΣI | 1..* | CodeableConcept | Categorization of document Binding: US Core DocumentReference Category (extensible) |
subject | SΣI | 1..1 | Reference(US Core Patient Profile) | Who/what is the subject of the document |
date | SΣI | 0..1 | instant | When this document reference was created |
author | SΣI | 0..* | Reference(US Core Practitioner Profile | PractitionerRole | US Core Organization Profile | Device | US Core Patient Profile | RelatedPerson) | Who and/or what authored the document |
authenticator | I | 0..1 | Reference(Practitioner | PractitionerRole | Organization) | Who/what authenticated the document |
custodian | SI | 0..1 | Reference(US Core Organization Profile) | Organization which maintains the document |
relatesTo | ΣI | 0..* | BackboneElement | Relationships to other documents |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!ΣI | 0..* | Extension | Extensions that cannot be ignored even if unrecognized |
code | ΣI | 1..1 | code | replaces | transforms | signs | appends Binding: DocumentRelationshipType (required) |
target | ΣI | 1..1 | Reference(DocumentReference) | Target of the relationship |
description | ΣI | 0..1 | string | Human-readable description |
securityLabel | ΣI | 0..* | CodeableConcept | Document security-tags Binding: All Security Labels (extensible) |
content | SΣI | 1..1 | BackboneElement | Document referenced |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!ΣI | 0..* | Extension | Extensions that cannot be ignored even if unrecognized |
attachment | SΣI | 1..1 | Attachment | Where to access the document us-core-6: DocumentReference.content.attachment.url or DocumentReference.content.attachment.data or both SHALL be present. |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations Slice: Unordered, Open by value:url |
contentType | SΣI | 1..1 | code | Mime type of the content, with charset etc. Binding: Mime Types (required) Example General: text/plain; charset=UTF-8, image/png |
language | ΣI | 0..1 | code | Human language of the content (BCP-47) Binding: CommonLanguages (preferred) Max Binding: AllLanguages Example General: en-AU |
data | SI | 0..1 | base64Binary | Data inline, base64ed |
url | SΣI | 0..1 | url | Uri where the data can be found Example General: http://www.acme.com/logo-small.png |
size | ΣI | 0..1 | unsignedInt | Number of bytes of content (if url provided) |
hash | ΣI | 0..1 | base64Binary | Hash of the data (sha-1, base64ed) |
title | ΣI | 0..1 | string | Label to display in place of the data Example General: Official Corporate Logo |
creation | ΣI | 0..1 | dateTime | Date attachment was first created |
format | SΣI | 0..1 | Coding | Format/content rules for the document Binding: DocumentReferenceFormatCodeSet (extensible) |
context | SΣI | 0..1 | BackboneElement | Clinical context of document |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!ΣI | 0..* | Extension | Extensions that cannot be ignored even if unrecognized |
encounter | SI | 0..1 | Reference(US Core Encounter Profile) | Context of the document content |
event | I | 0..* | CodeableConcept | Main clinical acts documented Binding: v3 Code System ActCode (example) |
period | SΣI | 0..1 | Period | Time of service that is being documented |
facilityType | I | 0..1 | CodeableConcept | Kind of facility where patient was seen Binding: FacilityTypeCodeValueSet (example) |
practiceSetting | I | 0..1 | CodeableConcept | Additional details about where the content was created (e.g. clinical specialty) Binding: PracticeSettingCodeValueSet (example) |
sourcePatientInfo | I | 0..1 | Reference(Patient) | Patient demographics from source |
related | I | 0..* | Reference(Resource) | Related identifiers or resources |
Documentation for this format |
DocumentReference
Summary of the Mandatory Requirements
- A code in
DocumentReference.status
with a required binding to DocumentReferenceStatus - A CodeableConcept in
DocumentReference.type
with a required binding to US Core DocumentReference Type - One or more CodeableConcepts in
DocumentReference.category
with an extensible binding to US Core DocumentReference Category - A Patient Reference in
DocumentReference.subject
- A Content in
DocumentReference.content
- which must have a Attachment value in
DocumentReference.content.attachment
- which should have a Coding value in
DocumentReference.content.format
with an extensible binding to DocumentReference Format Code Set
- which must have a Attachment value in
Summary of the Must Support Requirements
- One or more Identifiers in
DocumentReference.identifier
- An instant in
DocumentReference.date
- One or more Author References in
DocumentReference.author
- A Custodian Reference in
DocumentReference.custodian
- A Context in
DocumentReference.context
- which should have a Encounter Reference value in
DocumentReference.context.encounter
- which should have a Period value in
DocumentReference.context.period
- which should have a Encounter Reference value in
Summary of Constraints
- DocumentReference.content.attachment.url or DocumentReference.content.attachment.data or both SHALL be present.
Differential View
Snapshot View
Name | Flags | Card. | Type | Description & Constraints |
---|---|---|---|---|
DocumentReference | I | 0..* | A reference to a document | |
id | Σ | 0..1 | string | Logical id of this artifact |
meta | ΣI | 0..1 | Meta | Metadata about the resource |
implicitRules | ?!ΣI | 0..1 | uri | A set of rules under which this content was created |
language | I | 0..1 | code | Language of the resource content Binding: CommonLanguages (preferred) Max Binding: AllLanguages |
text | I | 0..1 | Narrative | Text summary of the resource, for human interpretation |
contained | 0..* | Resource | Contained, inline Resources | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!I | 0..* | Extension | Extensions that cannot be ignored |
masterIdentifier | ΣI | 0..1 | Identifier | Master Version Specific Identifier |
identifier | SΣI | 0..* | Identifier | Other identifiers for the document |
status | ?!SΣI | 1..1 | code | current | superseded | entered-in-error Binding: DocumentReferenceStatus (required) |
docStatus | ΣI | 0..1 | code | preliminary | final | amended | entered-in-error Binding: CompositionStatus (required) |
type | SΣI | 1..1 | CodeableConcept | Kind of document (LOINC if possible) Binding: US Core DocumentReference Type (required) Min Binding: US Core Clinical Note Type |
category | SΣI | 1..* | CodeableConcept | Categorization of document Binding: US Core DocumentReference Category (extensible) |
subject | SΣI | 1..1 | Reference(US Core Patient Profile) | Who/what is the subject of the document |
date | SΣI | 0..1 | instant | When this document reference was created |
author | SΣI | 0..* | Reference(US Core Practitioner Profile | PractitionerRole | US Core Organization Profile | Device | US Core Patient Profile | RelatedPerson) | Who and/or what authored the document |
authenticator | I | 0..1 | Reference(Practitioner | PractitionerRole | Organization) | Who/what authenticated the document |
custodian | SI | 0..1 | Reference(US Core Organization Profile) | Organization which maintains the document |
relatesTo | ΣI | 0..* | BackboneElement | Relationships to other documents |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!ΣI | 0..* | Extension | Extensions that cannot be ignored even if unrecognized |
code | ΣI | 1..1 | code | replaces | transforms | signs | appends Binding: DocumentRelationshipType (required) |
target | ΣI | 1..1 | Reference(DocumentReference) | Target of the relationship |
description | ΣI | 0..1 | string | Human-readable description |
securityLabel | ΣI | 0..* | CodeableConcept | Document security-tags Binding: All Security Labels (extensible) |
content | SΣI | 1..1 | BackboneElement | Document referenced |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!ΣI | 0..* | Extension | Extensions that cannot be ignored even if unrecognized |
attachment | SΣI | 1..1 | Attachment | Where to access the document us-core-6: DocumentReference.content.attachment.url or DocumentReference.content.attachment.data or both SHALL be present. |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations Slice: Unordered, Open by value:url |
contentType | SΣI | 1..1 | code | Mime type of the content, with charset etc. Binding: Mime Types (required) Example General: text/plain; charset=UTF-8, image/png |
language | ΣI | 0..1 | code | Human language of the content (BCP-47) Binding: CommonLanguages (preferred) Max Binding: AllLanguages Example General: en-AU |
data | SI | 0..1 | base64Binary | Data inline, base64ed |
url | SΣI | 0..1 | url | Uri where the data can be found Example General: http://www.acme.com/logo-small.png |
size | ΣI | 0..1 | unsignedInt | Number of bytes of content (if url provided) |
hash | ΣI | 0..1 | base64Binary | Hash of the data (sha-1, base64ed) |
title | ΣI | 0..1 | string | Label to display in place of the data Example General: Official Corporate Logo |
creation | ΣI | 0..1 | dateTime | Date attachment was first created |
format | SΣI | 0..1 | Coding | Format/content rules for the document Binding: DocumentReferenceFormatCodeSet (extensible) |
context | SΣI | 0..1 | BackboneElement | Clinical context of document |
id | 0..1 | string | Unique id for inter-element referencing | |
extension | I | 0..* | Extension | Additional content defined by implementations |
modifierExtension | ?!ΣI | 0..* | Extension | Extensions that cannot be ignored even if unrecognized |
encounter | SI | 0..1 | Reference(US Core Encounter Profile) | Context of the document content |
event | I | 0..* | CodeableConcept | Main clinical acts documented Binding: v3 Code System ActCode (example) |
period | SΣI | 0..1 | Period | Time of service that is being documented |
facilityType | I | 0..1 | CodeableConcept | Kind of facility where patient was seen Binding: FacilityTypeCodeValueSet (example) |
practiceSetting | I | 0..1 | CodeableConcept | Additional details about where the content was created (e.g. clinical specialty) Binding: PracticeSettingCodeValueSet (example) |
sourcePatientInfo | I | 0..1 | Reference(Patient) | Patient demographics from source |
related | I | 0..* | Reference(Resource) | Related identifiers or resources |
Documentation for this format |
Downloads: StructureDefinition: (XML, JSON), Schema: XML Schematron
Quick Start
Below is an overview of the required set of RESTful FHIR interactions - for example, search and read operations - for this profile. See the Conformance requirements for a complete list of supported RESTful interactions for this IG.
- See the General Guidance section for additional rules and expectations when a server requires status parameters.
- See the General Guidance section for additional guidance on searching for multiple patients.
Mandatory Search Parameters:
The following search parameters and search parameter combinations SHALL be supported.:
-
SHALL support fetching a DocumentReference using the
_id
search parameter:GET [base]/DocumentReference[id]
Example:
- GET [base]/DocumentReference/2169591
- GET [base]/DocumentReference?_id=2169591
Implementation Notes: Fetches a single DocumentReference. The document itself is represented as a base64 encoded binary data element or retrieved using the link provided by the resource. If the document is a relative link to a [Binary] resource like a resource reference, it can be subsequently retrieved using:
GET [base]/Binary/[id]
. (how to search by the logical id of the resource) -
SHALL support searching for all documentreferences for a patient using the
patient
search parameter:GET [base]/DocumentReference?patient=[reference]
Example:
- GET [base]/DocumentReference?patient=1137192
Implementation Notes: Fetches a bundle of all DocumentReference resources for the specified patient. See the implementation notes above for how to access the actual document. (how to search by reference)
-
SHALL support searching using the combination of the
patient
andcategory
search parameters:GET [base]/DocumentReference?patient=[reference]&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Example:
- GET [base]/DocumentReference?patient=1235541&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Implementation Notes: Fetches a bundle of all DocumentReference resources for the specified patient and category =
clinical-note
. See the implementation notes above for how to access the actual document. (how to search by reference and how to search by token) - SHALL support searching using the combination of the
patient
andcategory
anddate
search parameters:- including support for these
date
comparators:gt,lt,ge,le
- including optional support for composite AND search on
date
(e.g.date=[date]&date=[date]]&...
)
GET [base]/DocumentReference?patient=[reference]&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note&date={gt|lt|ge|le}[date]{&date={gt|lt|ge|le}[date]&...}
Example:
- GET [base]/DocumentReference?patient=1235541&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note&date=ge2019
Implementation Notes: Fetches a bundle of all DocumentReference resources for the specified patient and category =
clinical=note
and date. See the implementation notes above for how to access the actual document. (how to search by reference and how to search by token and how to search by date) - including support for these
-
SHALL support searching using the combination of the
patient
andtype
search parameters:GET [base]/DocumentReference?patient=[reference]&type={[system]}|[code]
Example:
- GET [base]/DocumentReference?patient=1316024&type=http://loinc.org|18842-5
Implementation Notes: Fetches a bundle of all DocumentReference resources for the specified patient and type. See the implementation notes above for how to access the actual document. (how to search by reference and how to search by token)
Optional Search Parameters:
The following search parameter combinations SHOULD be supported.:
- SHOULD support searching using the combination of the
patient
andstatus
search parameters:- including support for composite OR search on
status
(e.g.status={[system]}|[code],{[system]}|[code],...
)
GET [base]/DocumentReference?patient=[reference]&status={[system]}|[code]{,{[system]}|[code],...}
Example:
- GET [base]/DocumentReference?patient=1235541
Implementation Notes: Fetches a bundle of all DocumentReference resources for the specified patient and status. See the implementation notes above for how to access the actual document. (how to search by reference and how to search by token)
- including support for composite OR search on
- SHOULD support searching using the combination of the
patient
andtype
andperiod
search parameters:- including support for these
period
comparators:gt,lt,ge,le
- including optional support for composite AND search on
period
(e.g.period=[date]&period=[date]]&...
)
GET [base]/DocumentReference?patient=[reference]&type={[system]}|[code]&period={gt|lt|ge|le}[date]{&period={gt|lt|ge|le}[date]&...}
Example:
- GET [base]/DocumentReference?patient=2169591&type=http://loinc.org |34133-9&period=ge2019
Implementation Notes: Fetches a bundle of all DocumentReference resources for the specified patient and type and period. See the implementation notes above for how to access the actual document. (how to search by reference and how to search by token and how to search by date)
- including support for these