US Core Implementation Guide
4.1.0 - STU4 Ballot
US Core Implementation Guide
4.1.0 - STU4 Ballot
This page is part of the US Core (v4.1.0: STU5 Ballot 1) 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 
This section outlines important definitions, interpretations, and requirements common to all US Core actors used in this guide. The conformance verbs - SHALL, SHOULD, MAY - used in this guide are defined in FHIR Conformance Rules.
The US Core Profiles were originally designed to meet the 2015 Edition certification criterion for Patient Selection 170.315(g)(7), and Application Access – Data Category Request 170.315(g)(8). They were created for each item in the 2015 Edition Common Clinical Data Set (CCDS). The Location, Organization, and Practitioner Profiles are not called out specifically in the certification criteria but are included because they are directly referenced by other profiles. The US Core Profiles are informed by the prior Data Access Framework and the Argonaut Data Query Implementation Guides. However, the profiles here are stand alone and include requirements from the U.S. Core Data for Interoperability (USCDI) v1.
The table below lists the US Core Profile and FHIR Resources used for the corresponding USCDI Data elements:
With each major version in FHIR, the core data models have undergone changes. The FHIR core specification provides a base resource differential to help implementers navigate version changes.
The search expectations and US Core Profiles have been developed and tested using logical FHIR ids. Therefore a reference to a US Core resource SHOULD include a logical id (Reference.reference), not an identifier (Reference.identifier).
Many of the profiles in this guide reference other FHIR resources that are also US Core Profiles. This is defined in the formal profile definitions. For example, US Core CareTeam Profile references US Core Patient. For any other references to base FHIR resources1 or not formally defined in a US Core Profiles, the referenced resource SHOULD be a US Core Profile if a US Core Profile exists for the resource type. For example, although Condition.asserter is not constrained by this guide, the reference to Patient or Practitioner SHOULD be a valid US Core Patient or US Core Practitioner. US Core Resources in the differential view and marked as “Must Support” follow the Must Support rules described in Conformance Expectations. Other resources allowed in the base FHIR specification may be referenced even though the current publication framework does not display them. For example, RelatedPerson is an allowed target reference in DocumentReference.author.
When responding to a query, servers SHOULD NOT use inline contained resources to represent the returned data. The only time contained resource can be used is when the source data exists only within the context of the FHIR transaction. For example, the Medication List Guidance page describes how a contained Medication in MedicationRequest is used for representing the medication. If referencing a contained resource in a US Core Profile, the contained resource SHOULD be a US Core Profile if a US Core Profile exists for the resource type. Further guidance about the general use case for contained can be found in the base FHIR specification.
There are situations when information on a particular data element is missing and the source system does not know reason for the absence of data. If the source system does not have data for an element with a minimum cardinality = 0 (including elements labeled Must Support), the data element is omitted from the resource. If the source system does not have data for a Mandatory element (in other words, where the minimum cardinality is > 0), the core specification provides guidance which is summarized below:
unknown - The value is expected to exist but is not known.Example: Patient resource where the patient name is not available.
{
"resourceType" : "Patient",
...
"name": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
]
"telecom" :
...
}
display element.unknown from the DataAbsentReason Code System.Example: AllergyIntolerance resource where the manifestation is unknown.
...
"reaction" : [
{
"manifestation" : [
{
"coding" : [
{
"system" : "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"code" : "unknown",
"display" : "unknown"
}
]
}
]
}
]
...
if the value set does not have the appropriate “unknown” concept code you must use a concept from the value set otherwise the instance will not be conformant
AllergyIntolerance.clinicalStatus*Condition.clinicalStatus*DocumentReference.statusImmunization.statusGoal.lifecycleStatus*The clinicalStatus element has the following constraints: SHALL be present if verification status is not entered-in-error and SHALL NOT be present if verification Status is entered-in-error.
If one of these status code is missing, a 404 http error code and an OperationOutcome SHALL be returned in response to a read transaction on the resource. If returning a response to a search, the problematic resource SHALL be excluded from the search set and a warning OperationOutcome SHOULD be included indicating that additional search results were found but could not be compliantly expressed and have been suppressed.
In situations where the specific piece of data is hidden due to a security or privacy reason, using a code from the DataAbsentReason Code System such as masked may exceed the data receiver’s access rights to know and should be avoided. For elements with a minimum cardinality = 0 (including elements labeled Must Support), the element SHOULD be omitted from the resource. For Mandatory elements (in other words, where the minimum cardinality is > 0), use the code unknown following the guidance on Missing Data in the section above.
Both the US Core Vital Signs Profile and US Core Laboratory Result Observation Profile bind the valueQuantity datatypes to the UCUM code system. A FHIR UCUM Codes value set that defines all UCUM codes is in the FHIR specification. This guidance specifies how to represent the Quantity datatype when the correct UCUM units are missing or the units are missing altogether which will likely occur in the real world.
UCUM code provided
"valueQuantity": {
"value": 26.0,
"unit": "g/mL",
"system": "http://unitsofmeasure.org",
"code": "g/mL"
}
free text units only:
unit element. "valueQuantity": {
"value": 26.0,
"unit": "RR",
}
no units
"valueQuantity": {
"value": 26.0
}
Clinical information that has been entered-in-error in the patient’s record needs to be represented by the FHIR Server in a way so that Clients can expose the corrected information to their end users.
Server Recommendations:
entered-in-error or inactive.entered-in-error:
The US Core CarePlan Profile requires a narrative summary of the patient assessment and plan of treatment. However, any US Core Profile MAY include a human-readable narrative that contains a summary of the resource and may be used to represent the content of the resource to a human. For further guidance, refer the Narrative documentation in the FHIR Specification.
There is a basic need be able to access records in your language, and the data provider should do their best to translate (safely) to the language being requested. Understanding that this will be variably complete depending on the nature of the record. For example translating the following elements is relatively straightforward:
Coding.displayAttachment.titleThe following guidelines outline how to request and return a resource in the requested language.
Accept-Language header.language element with a code which is based on the underlying language of record, not the requested language.
Servers SHALL use the http://hl7.org/fhir/StructureDefinition/language extension when the language of a display, etc is known to be different to the stated (or inferred) language.
Example
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
<id value="language-example-1"/>
<meta>
[...snip...]
</meta>
<language value="es"/>
<!--0..1 Language of the resource content in this case Spanish-->
<text>
[...snip...]
</text>
<extension url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-race">
<extension url="ombCategory">
<valueCoding>
<system value="urn:oid:2.16.840.1.113883.6.238"/>
<code value="2106-3"/>
<display value="White">
<!--Human Language extension-->
<extension url="http://hl7.org/fhir/StructureDefinition/language">
<valueCode value="en"/>
<!--English is different from stated language-->
</extension>
</display>
</valueCoding>
</extension>
[...snip...]
Servers SHALL use the http://hl7.org/fhir/StructureDefinition/translation extension when the server is providing additional translations by its own choice or in response to a different Accept-Language than what the resource is stored in.
Example
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
<id value="language-example-2"/>
<meta>
[...snip...]
</meta>
<language value="en"/>
<!--0..1 Language of the resource content: English-->
<text>
[...snip...]
</text>
<extension url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-race">
<extension url="ombCategory">
<valueCoding>
<system value="urn:oid:2.16.840.1.113883.6.238"/>
<code value="2106-3"/>
<display value="White">
<!-- Translation -->
<extension
url="http://hl7.org/fhir/StructureDefinition/translation" >
<extension url="lang"> <!-- 1..1 Code for Language -->
<valueCode value="es"/><!-- 0..1 Value of extension -->
</extension>
<extension url="content"> <!-- 1..1 Content in other Language -->
<valueString value="Blanca">
</extension>
</extension>
</display>
</valueCoding>
</extension>
[...snip...]
Servers SHOULD make it known what languages are supported in their CapabilityStatement(s) using this extension2:
http://hl7.org/fhir/5.0/StructureDefinition/extension-CapablilityStatement.acceptLanguage
For further guidance on language and locale for generation of the resource narrative, see the Multi-language support for Narratives in the core specification.
For fetching a resource interactions on profile pages are defined with the following syntax:
GET [base]/[Resource-type]/[id] {parameters}
For more information see the FHIR RESTful API
The FHIR RESTful Search API requires that servers that support search SHALL support the http POST based search. However, for all the supported search interactions in this guide, servers SHALL also support the GET based search. Note that these requirements for parameters apply to both GET and POST based queries.
For this guide, all the search interactions use the GET command with the following syntax:
GET [base]/[Resource-type]?[parameter1]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]{&[parameter2]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]&...}
token type searchparameter (how to search by token), the syntax {system|}[code] means that the system value is optional for the client to supply.:
reference type searchparameter (how to search by reference), the syntax {Type/}[id] means that the Type value is optional for the client to supply:
date type searchparameter (how to search by date), the syntax data={gt|lt|ge|le}[date] means the date comparators “gt”, “lt”, “ge”, and “le” are optional. Date type searches without a comparator prefix are equivalent to searches with the “eq” comparator even if a server does not support the comparator.| {:m1 | m2 | …}: The list of supported search parameter modifiers |
| {c1 | c2 | …}: The list of supported search parameter comparators |
| {¶meter2={:m1 | m2 | …}={c1 | c2 | …}[value1{,value2,…}&…}: Optional multiple ‘AND’ search parameters |
In the simplest case, a search is executed by performing a GET operation in the RESTful framework:
GET [base]/[Resource-type]?name=value&...
For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example, the Observation resource the name “code” for search on the LOINC code. For more information see the FHIR RESTful Search API
Note that the patient may be implicit in the context in some implementations (e.g. using SMART). Then the patient parameter can be omitted:
GET [base]/[Resource-type]{?other-parameters}
When searching using the date type searchparameter (how to search by date):
date and to the second + time offset for elements of datatype dateTime.date and to the second + time offset for elements of datatype dateTime.The table below summarizes the date precision:
| SearchParameter | Element Datatype | Minimum Date Precision | Example |
|---|---|---|---|
| date | date | day | GET [base]/Patient?family=Shaw&birthdate=2007-03-20 |
| date | dateTime, Period | second + time offset | GET [base]Observation?patient=555580&category=laboratory&date=ge2018-03-14T00:00:00-08:00 |
Servers are strongly encouraged to support a query for resources without requiring a status parameter. However, if business requirements prohibit this they SHALL follow the guidelines here.
For searches where the client does not supply a status parameter, an implementation’s business rules may override the FHIR RESTful search expectations and require a status parameter to be provided. These systems are allowed to reject such requests as follows:
400 statusIf a system doesn’t support a specific status code value that is queried, search results SHOULD return an http 200 status with search bundle containing resources matching the search criteria and an OperationOutcome warning the client which status code value is not supported.
For example, in a query enumerating all the AllergyIntolerance.verificationStatus statuses to a system that supports concepts unconfirmed, confirmed, entered-in-error but not refuted, the search parameter is referring to an unsupported code since refuted is not known to the server.
Storyboard for this example
This example is based upon the following scenario:
Patient 1137192 uses an App to request all his encounters from the provider. The provider system requires status and rejects the request returning a 400 and an OperationOutcome specifying that a status parameter is required for this search.
Request:
Get “all encounters” for a patient 1137192 by querying Encounter using the patient search parameter.
GET [base]/Encounter?patient=1137192
Response:
Instead of returning a search Bundle resource containing all the Encounter for the patient, the server return a 400 Not Found and an OperationOutcome detailing that a status parameter is required for this search.
HTTP/1.1 400 Not Found
[other headers]
{
"resourceType": "OperationOutcome",
"id": "no-status",
"issue": [
{
"severity": "error",
"code": "business-rule",
"details": {
"text": "A \"status\" search parameter is required for this search"
},
"diagnostics": "valid statuses for Encounter include planned | arrived | triaged | in-progress | onleave | finished | cancelled | entered-in-error | unknown"
}
]
}
CapabilityStatement.rest.resource.interaction.documentation.Currently, most EHRs permit queries that provide a single patient id, but do not support the comma separated query or a query where the patient parameter is omitted as described in the standard FHIR REST API. Instead, a user facing app can perform multiple “parallel” queries on a list of patient ids. Alternatively, the FHIR Bulk Data Access (Flat FHIR) specification can be used to perform a “back end” system level query to access a large volumes of information on a group of individuals or when trying to identify and query against an unknown population such as when looking for population based research data or for population-level queries for public health surveillance.
However, neither specification defines how a user facing provider app is able to seek realtime “operational” data on multiple patients (such as all patients with recent lab results). Opportunities to add this capability to this guide are discussed in Future of US Core
This IG does not support patient compartment based searches.
US Core servers are not required to resolve full URLs that are external to their environment.
In order to manage the number of search results returned, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links. See the managing returned resources in the FHIR specification for more information.
Footnotes:
For example, the base Location resource is being referenced by the US Core Encounter and US Core PractitionerRole resources. ↩
This extension is converted from a new element in a future version of CapabilityStatement. ↩
IG © 2021+ HL7 International - Cross-Group Projects. Package hl7.fhir.us.core#4.1.0 based on FHIR 4.0.1. Generated 2021-12-06
Links: Table of Contents |
QA Report
| Version History |
Search |
|
Propose a change