US Core Implementation Guide
5.0.1 - STU5 Release
US
US Core Implementation Guide
5.0.1 - STU5 Release
US
This page is part of the US Core (v5.0.1: STU5) based on FHIR R4. This is the current published version in its permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions 
This page documents important 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 Profiles and Extensions page list the US Core Profiles and have been defined for this implementation guide. Core Profile StructureDefinitions defines the minimum elements, extensions, vocabularies and value sets which SHALL be present when using the profile. Each Profile page has a “Quick Start” guide to the supported FHIR RESTfUL transactions for each Profile
The Profile elements consist of both Mandatory and Must Support elements. Mandatory elements are elements with an minimum cardinality of 1 (min=1). The base FHIR Must Support guidance requires specifications to define exactly the support expected for profile elements labeled Must Support. The Must Support page illustrates how these elements are displayed and defines the rules for interpreting profile elements and subelements labeled Mandatory and Must Support for requesters and responders.
The Capability Statements page outlines conformance requirements and expectations for the US Core Servers and Client applications. The US Core Server CapabilityStatement and US Core Client CapabilityStatement identify the specific profiles and RESTful transactions that need to be supported. Note that the individual US Core profiles identify the structural constraints, terminology bindings and invariants. Similarly, the individual US Core SearchParameter and Operation resources specify how they are understood by the server. However, implementers must refer to the CapabilityStatement for details on the RESTful transactions, specific profiles and the search parameters applicable to each of the US Core actors.
There are two different ways to implement US Core:
Systems may deploy, and support, one or more US Core Profiles to represent clinical information. They are using the profile’s content model without any expectations to implement the US Core interactions.
An example scenario would be a server using only the FHIR Bulk Data Access (Flat FHIR) approach to export resources needed for the US Core Data for Interoperability. For this server, the US Core interactions are unnecessary.
To support a US Core Profile, a server:
CapabilityStatement.rest.resource.supportedProfile element
the US Core Profile’s official or “canonical” URL can be found on each US Core Profile page
example CapabilityStatement snippet for a server supporting the US Core Patient Profile:
{
"resourceType": "CapabilityStatement",
...
"rest": [
{
"mode": "server",
...
"resource": [
...
{
"type": "Patient",
"supportedProfile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
],
...
}
]
}
]
}
Systems may deploy, and support, one or more US Core Profiles to represent clinical information and the US Core interactions to access the information. Systems that implement both can claim conformance to US Core Profile content structure and the RESTful interactions defined for it. This is done by implementing all or parts of the USCore CapabilityStatement into their capabilities.
A server that certifies to the 21st Century Cures Act for accessing patient data must implement all components in the USCDI and the US Core CapabilityStatement.
To claim conformance to a US Core Profile a server:
SHALL declare conformance with the US Core Server Capability Statement by including its official URL in the server’s CapabilityStatement.instantiates element: http://hl7.org/fhir/us/core/CapabilityStatement/us-core-server
CapabilityStatement.rest.resource.supportedProfile elementexample CapabilityStatement snippet for a server conforming to the US Core Patient Profile:
{
"resourceType": "CapabilityStatement",
...
"instantiates": [
"http://hl7.org/fhir/us/core/CapabilityStatement/us-core-server"
],
...
"rest": [
{
"mode": "server",
...
"resource": [
...
{
[
{
"extension": [
{
"url": "required",
"valueString": "birthdate"
},
{
"url": "required",
"valueString": "name"
}
],
"url": "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
},
{
"extension": [
{
"url": "required",
"valueString": "family"
},
{
"url": "required",
"valueString": "gender"
}
],
"url": "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
},
{
{
"url": "required",
"valueString": "birthdate"
},
{
"url": "required",
"valueString": "family"
}
],
"url": "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
},
{
"extension": [
{
"url": "required",
"valueString": "gender"
},
{
"url": "required",
"valueString": "name"
}
],
"url": "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
}
]
}
]
"type": "Patient",
"supportedProfile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
],
"interaction": [
{
"code": "create"
},
{
"code": "search-type"
},
{
"code": "read"
}
],
"referencePolicy": [
"resolves"
],
"searchRevInclude": [
"Provenance:target"
],
"searchParam": [
{
"name": "_id",
"definition": "http://hl7.org/fhir/us/core/SearchParameter/us-core-patient-id",
"type": "token"
},
{
"name": "identifier",
"definition": "http://hl7.org/fhir/us/core/SearchParameter/us-core-patient-identifier",
"type": "token",
"documentation": "The client **SHALL** provide at least a code value and **MAY** provide both the system and code values.\n\nThe server **SHALL** support both."
},
{
"name": "name",
"definition": "http://hl7.org/fhir/us/core/SearchParameter/us-core-patient-name",
"type": "string"
}
],
...
}
]
}
]
}
The rules provided here summarize the requirements defined by FHIR Terminology for coded elements (CodeableConcept, Coding, and code datatypes).
Required binding to a value set definition means that one of the codes from the specified value set SHALL be used. For CodeableConcept using only text is not valid, but multiple codings (translations) are permitted as is discussed below.
For example, the US Core AllergyIntolerance Profile clinicalStatus element has a required binding to the AllergyIntoleranceClinicalStatusCodes ValueSet. When claiming conformance to this profile:
AllergyIntolerance.clinicalStatus.code.US Core Requestors SHALL be capable of processing the code in AllergyIntolerance.clinicalStatus.code.
Because of the FHIR conformance rule:
If an extensible binding is applied to an element with maximum cardinality > 1, the binding applies to all the elements.(Terminology Binding Extensible)
FHIR profiles use slicing when a coded element is a repeating element and a particular value set is desired for at least one of the repeats. This is a special case where a required value set binding is used to differentiate the repeat. In this guide, the minimum cardinality for these ‘slices’ is set to 0 so that other codes are allowed when no suitable code exists in the value set (equivalent to Extensible Binding below). Note that the introduction of slicing by valueset does not affect the over the wire structure or validation of instances of these resources. The example in figure 5 below illustrates this structure for the repeating Condition.category element:
This structure, by being 0..*, allows servers to send concepts not in the required value set.
Extensible Binding to a value set definition means that one of the codes from the specified value set SHALL be used if an applicable concept is present, but if no suitable code exists in the value set, alternate code(s) may be provided in its place. For CodeableConcept multiple codings are permitted and this rule applies to one of the codings. Also for CodeableConcept if only text is available, then just text may be used.
To illustrate extensible binding for CodeableConcept datatype, the US Core AllergyIntolerance Profile code element has an extensible binding to the VSAC ValueSet “Common substances for allergy and intolerance documentation including refutations” Allergy. When claiming conformance to this profile:
AllergyIntolerance.code.code if the concept exists in the value setAllergyIntolerance.code.textif only text is available.US Core Requestors SHALL be capable of processing the code in AllergyIntolerance.code.code or text in AllergyIntolerance.code.text
Although the FHIR guidance for extensible bindings indicates that all conceptual overlaps including free text be mapped the coded values in the bindings, US Core guidance provides more flexibility for situations where implementers cannot fully comply with the FHIR base guidance. This flexibility is sometimes necessary and expected for legacy and text only data. For newly recorded, non legacy data, a system SHOULD meet the conformance of the value set.
For example, the US Core Procedure Codes and US Core Condition Codes value sets contain a number of high-level abstract codes. For data not captured by the system transmitting the information, the coded data should be automatically converted to a fine-grained code from the specified value set. If this is not possible, the system can provide the existing code or the free text, and a high-level abstract code, such as SNOMED CT ‘Procedure’, to remain conformant with the extensible binding.
Alternate codes may be provided in addition than the standard codes defined in required or extensible value sets. The alternate codes are called “translations”. These translations may be equivalent to or narrower in meaning to the standard concept code.
Example of multiple translation for Body Weight concept code.
"code": {
"coding": [
{
"system": "http://loinc.org", //NOTE:this is the standard concept defined in the value set//
"code": "29463-7",
"display": "Body Weight"
},
//NOTE:this is a translation to a more specific concept
{
"system": "http://loinc.org",
"code": "3141-9",
"display": "Body Weight Measured"
},
//NOTE:this is a translation to a different code system (Snomed CT)
{
"system": "http://snomed.info/sct",
"code": “364589006”,
"display": "Body Weight"
}
//NOTE:this is a translation to a locally defined code
{
"system": "http://AcmeHealthCare.org",
"code": “BWT”,
"display": "Body Weight"
}
],
"text": "weight"
},
Example of translation of CVX vaccine code to NDC code.
"vaccineCode" : {
"coding" : [
{
"system" : "http://hl7.org/fhir/R4/sid/cvx",
"code" : "158",
"display" : "influenza, injectable, quadrivalent"
},
{
"system" : "http://hl7.org/fhir/R4/sid/ndc",
"code" : "49281-0623-78",
"display" : "FLUZONE QUADRIVALENT"
}
]
},
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 SHALL be omitted from the resource. If the data element is a a Mandatory element (in other words, where the minimum cardinality is > 0), it SHALL be present for even if the source system does not have data. The core specification provides guidance for what to do in this situation, 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://terminology.hl7.org/CodeSystem/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://terminology.hl7.org/CodeSystem/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 is conditionally mandatory based on resource specific constraints.
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.
The FHIR RESTful Search API requires that servers that support search SHALL support the http POST based search. For all the supported search interactions in this guide, servers SHALL also support the GET based search.
token type searchparameter (how to search by token)
reference type searchparameter (how to search by reference)
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.
IG © 2022+ HL7 International - Cross-Group Projects. Package hl7.fhir.us.core#5.0.1 based on FHIR 4.0.1. Generated 2022-06-22
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change