US Core Implementation Guide
4.0.0 - STU4 Release
US Core Implementation Guide
4.0.0 - STU4 Release
This page is part of the US Core (v4.0.0: STU4) 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 page defines how CapabilityStatements are used and the expectations for mandatory and must support elements in the US Core Profiles. It provides guidance on how a system may support only the resources as profiled by US Core to represent clinical information (Profile Support) versus a system claiming conformance to both the US Core Profile content structure and the RESTful interactions defined for it (Profile Support + Interaction Support). Note that 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 sections below illustrate how these elements are displayed and define 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 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"
}
],
...
}
]
}
]
}
Each profile provides several different formal views of all the must support elements in a tree format under tabs labeled “Differential Table”, “Snapshot Table”, and “Snapshot Table (Must Support)”.
The elements labeled Must Support in the “Differential Table” view are flagged with an S. An example of this is illustrated in Figure 1.
In the “Snapshot Table” view in Figure 2, all the must support elements defined for the profile, and any mandatory or must support elements inherited from a base profile (e.g. US Core Body Height Profile based on Vital Signs Profile), are flagged with an S. An example of the “Snapshot Table” is shown in Figure 2.
In the “Snapshot Table (Must Support)” view, all the elements presented in the view are either mandatory or must support elements for conformance to the profile. These elements are defined in the US Core Profile, mandatory elements inherited from the base specification and, for the US Core Vital Signs profiles, any mandatory or must support elements inherited from the FHIR base Vital Signs profile. An example of the “Snapshot Table (Must Support)” is shown in Figure 3.
When an element is mandatory (min=1), the data is expected to always be present. Very rarely it may not be and guidance for when data is missing is provided in the Missing Data section and in the next section. The convention in this guide is to mark all min=1 elements as must support unless the are nested under optional element. An example of this is CarePlan.status.
For querying and reading US Core Profiles, Must Support on any profile data element SHALL be interpreted as follows (see the Future of US Core page for writing and updating US Core Profiles):
unknown.The terms US Core Responder Actor US Core Requestor Actor are used throughout the guide and typically refer to a server or a client.
Readers are advised to understand FHIR Terminology requirements, FHIR RESTful API based on the HTTP protocol, along with FHIR Data Types, FHIR Search and FHIR Resource formats before implementing US Core requirements.
In addition to the guidance provided by FHIR Terminology, Coded elements (CodeableConcept, Coding, and code datatypes) which are marked as Must Support follow the rules for their respective bindings.
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.
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 Code 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"
}
]
},
The StructureDefinitions define the US Core Profiles and the ElementDefinition.pattern which is used almost exclusively for the CodeableConcept and Coding datatypes. If the element is marked as must support and defined by a pattern then the pattern defines the elements and element values that the server SHALL be capable of providing.
For example the US Core DiagnosticReport Profile for Laboratory Results Reporting category element is defined with a pattern requiring fixed values in DiagnosticReport.category.coding.system and DiagnosticReport.category.coding.code for a Coding element. When claiming conformance to this profile:
DiagnosticReport.categoryUS Core Requestors SHALL be capable of processing these values in DiagnosticReport.category
Primitive elements are are single elements with a primitive value. If they are marked as must support, then the server SHALL be capable of providing the element value to meet the must support requirement.
For example, the [US Core DiagnosticReport Profile] issued element is a primitive instant datatype. When claiming conformance to this profile:
DiagnosticReport.issuedUS Core Requestors SHALL be capable of processing the value in DiagnosticReport.issued
Complex element are composed of primitive and/or other complex elements. In addition to the general guidance for complex elements in this section, there is additional must support guidance in other sections for the following complex datatypes:
For any complex element marked as must support, the server SHALL be capable of providing at least one of the sub-element values. If any sub-element is marked as must support it must meet the must support requirements as well and satisfy the must support requirement for the parent element.
For example, the US Core DiagnosticReport Profile for Report and Note exchange presentedForm element is labeled must support and has no must support sub-elements. When claiming conformance to this profile:
DiagnosticReport.presentedForm sub-element.US Core Requestors SHALL be capable of processing the value in DiagnosticReport.presentedForm.
For example, the US Core Patient Profile name element is labeled must support and has must support sub-elements “family” and “given”. When claiming conformance to this profile:
Patient.name.family and Patient.name.given.US Core Requestors SHALL be capable of processing the value in value in Patient.name.family and Patient.name.given.
On the other hand, if any sub-element is marked as must support and the parent element is not, there is no expectation that you must support the parent. However, if the parent element is represented in the structure you must support the sub-element(s) marked as must support. There are no examples of US Core profiles that have this structure defined.
Systems can support the other elements, but this is not a requirement of US Core. The U.S. Core Data for Interoperability (USCDI) v1 may require other elements, for example suffix.
In certain profiles only specific resource references are labeled as Must Support.
For example, the US Core DocumentReference Profile author US Core Practitioner Profile is labeled Must Support. When claiming conformance to the US Core DocumentReference Profile:
Systems can support other references but this is not a requirement of US Core.
In certain profiles only a single resource reference is present on an element labeled Must Support.
For example, the US Core AllergyIntolerance Profile patient is labeled Must Support. When claiming conformance to the US Core AllergyIntolerance Profile:
AllergyIntolerance.patient with a valid reference to a US Core Patient Profile.AllergyIntolerance.patient with a valid reference to a US Core Patient Profile.
Some elements allow different data types (e.g. Observation.effective[x]) for their content. In these situations, only specific data type choice elements are labeled as Must Support.
For example, the US Core Laboratory Result Observation Profile effectiveDateTime is labeled Must Support. When claiming conformance to the US Core Laboratory Result Observation Profile:
Observation.effectiveDateTime.Observation.effectiveDateTime.Systems MAY support populating and processing other choice elements (such as, Observation.effectivePeriod) but this is not a requirement of US Core.
For the US Core Laboratory Result Observation Profile value element, multiple elements are labeled Must Support.
When claiming conformance to the US Core Laboratory Result Observation Profile:
Observation.valueQuantity, Observation.valueCodeableConcept, and Observation.valueString.Observation.valueQuantity, Observation.valueCodeableConcept, and Observation.valueString.Systems can support the other elements, but this is not a requirement of US Core.
There are several instances in this Guide where there is a choice of supporting one or another profile element to meet the must support requirement. In such instances, the server SHALL support at least one such element, and the client application SHALL support all such elements. There is no way to define this in a computable way, but these instances are clearly documented in the Profile specific implementation guidance sections.
For example:
US Core Medication Request Profile - The MedicationRequest resource can represent that information is from a secondary source using either a boolean flag or reference in MedicationRequest.reportedBoolean, or a reference using MedicationRequest.reportedReference to Practitioner or another resource type. Although both are marked as must support, servers are not required to support both a boolean and a reference, but SHALL choose to support at least one of these elements.
IG © 2021+ HL7 International - US Realm Steering Committee. Package hl7.fhir.us.core#4.0.0 based on FHIR 4.0.1. Generated 2021-06-28
Links: Table of Contents |
QA Report
| Version History |
Search |
|
Propose a change