Release 5
This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version in it's permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2
| FHIR Infrastructure | Maturity Level: N | Normative (from v4.0.0) | Security Category: N/A | Compartments: No defined compartments |
This specification defines a series of different types of resource that can be used to exchange and/or store data in order to solve a wide range of healthcare related problems, both clinical and administrative. In addition, this specification defines several different ways of exchanging the resources.
A resource is an entity that:
Resources have multiple representations.
The following optional elements and properties are defined for all resources:
Resource is the ancestor of DomainResource from which most recources are derived. Bundle, Parameters, and Binary extend Resource directly.
Note: there is documentation for the Structure, UML, XML, and JSON representations of the resource structure.
Structure
| Name | Flags | Card. | Type | Description & Constraints | ||||
|---|---|---|---|---|---|---|---|---|
| «A»N | Base | Base Resource Elements defined in Ancestors: | ||||||
| Σ | 0..1 | id | Logical id of this artifact | |||||
| Σ | 0..1 | Meta | Metadata about the resource | |||||
| ?!Σ | 0..1 | uri | A set of rules under which this content was created | |||||
| 0..1 | code | Language of the resource content Binding: All Languages (Required)
| ||||||
UML Diagram (Legend)
Structure
| Name | Flags | Card. | Type | Description & Constraints | ||||
|---|---|---|---|---|---|---|---|---|
| «A»N | Base | Base Resource Elements defined in Ancestors: | ||||||
| Σ | 0..1 | id | Logical id of this artifact | |||||
| Σ | 0..1 | Meta | Metadata about the resource | |||||
| ?!Σ | 0..1 | uri | A set of rules under which this content was created | |||||
| 0..1 | code | Language of the resource content Binding: All Languages (Required)
| ||||||
Additional definitions: Master Definition XML + JSON + ShEx, the spreadsheet version & the dependency analysis, Resource Representation XML + JSON + Turtle
| Path | ValueSet | Type | Documentation |
|---|---|---|---|
| Resource.language | AllLanguages (a valid code from Tags for the Identification of Languages | Required | This value set includes all possible codes from BCP-47 (see http://tools.ietf.org/html/bcp47) |
| Common Languages | starter |
There are two different ways to identify a resource:
Each resource has an id element which contains the "logical id" of the resource
assigned by the server responsible for storing it. Resources always have a known logical id
except for a few special cases (e.g. when a new resource is being sent to a server to assign
a logical id in the create interaction).
The logical id is unique within the space of all resources of the same type on
the same server. Once assigned by the server, the id is never changed.
The location of a resource instance is an absolute URI constructed from the server
base address at which the instance is found, the resource type and the Logical ID, such as
http://test.fhir.org/r5/rest/Patient/123 (where 123 is the Logical Id of a Patient resource).
When the location is an HTTP address, this address can generally be used to retrieve or manipulate the resource.
Note that implementations SHOULD NOT assume that the location of a resource is always resolvable
to an accessible server - it may be temporarily unavailable, or not available by policy (e.g. firewalls) or in some
cases, it might not actually exist (e.g. use of resource outside a RESTful environment).
Resources reference each other by their location. These references are allowed to be absolute
or relative (see Resource References for further discussion).
When a resource is copied from one server to another server, the copy might or might not keep the same logical id on the new server. This depends on replication and server policy. For further details, see Managing Resource Identity (including "Consistent Resource Identification").
Logical ids (and therefore locations) are case sensitive. Logical Ids are always opaque, and external systems need not and should not attempt to determine their internal structure. A logical id SHALL always be represented in the same way in resource references and URLs. Ids can be up to 64 characters long, and contain any combination of upper and lowercase ASCII letters, numerals, "-" and ".".
In some contexts, resources are not associated with location on a RESTful server, either because they are only created transiently for transfer between systems, or the systems are not using RESTful servers. In these cases, resources may be assigned some kind of location anyway, for purposes of consistency, or they might not have an assigned logical id, and they are identified based on other kinds of identifiers. See Resolving references in Bundles for one method of using resources not associated with RESTful servers.
In general, identifiers are sometimes categorised into one of three categories: Business, informational, and instance.
In these terms, the logical id is an instance identifier, and all the other
identifiers are loosely called "business" identifiers. Note that due to real-world practices
around IDs, business identifiers are often used to identify things by proxy e.g. identifying
multiple different patient records for the same person by the same driver's license number.
Although the logical id of a resource changes as it moves from server to server, all copies
of the resource refer to the same underlying concept, and this concept may also be represented
in other formats (variously, HL7 V2 ,
CDA
, XDS, and many more).
Each representation carries common identifiers that identify the underlying concept (also called "real-world entity")
consistently across all contexts of use. This is known as the
business identifier, and is found in
the identifier element, which has the type Identifier.
All resources that have an identifier element support searching by the identifier, so
that records can be located by that method. So if an HL7 V2
message has the following OBR:
OBR|1|845439^GHH OE|1045813^GHH LAB|1554-5^GLUCOSE^LN|||200202150730|...
Then the DiagnosticReport it represents can be located using the following query:
GET [base]/DiagnosticReport?identifier=1045813
Most resources have a logical master server, the system on which the
record first is created, and which manages the record directly. In
the master system, the Logical ID might be the same value
found in the business identifier since the master server can enforce
business practices that make for stable identifiers. This is usually
not a safe practice on secondary systems which are not in a position to
enforce their required identifier consistency.
Some resource types have a defined element url which is the 'canonical URL'
that always identifies the resource. This is a special kind of Business Identifier.
Note that the element actually contains a URI, but is named url for legacy reasons.
The canonical URL serves as a stable logical identifier for the resource, and is the preferred way to reference a conformance or knowledge resource. The canonical URL SHOULD also resolve to the location where the master copy of the artifact is found, though it is not always possible to arrange this. The canonical URL SHALL NOT refer to some other resource (though it may resolve to a different version of the same resource).
See Canonical references for further discussion of canonical references and the canonical data type. The following resources have canonical URLs:
Business Identifiers are the preferred basis to recognize the same content on different systems. For example:
GET http://a.company.example.com/Patient/23
<Patient xmlns="http://hl7.org/fhir">
<id value="23"/>
<identifier>
<system value="http://a.particular.system/identifier"/>
<value value="123456"/>
</identifier>
</Patient>
GET http://other.company.example.com/fhir/Patient/5860200e-0ee3-42f5-8095-506e18dc9ca2
<Patient xmlns="http://hl7.org/fhir">
<id value="5860200e-0ee3-42f5-8095-506e18dc9ca2"/>
<identifier>
<system value="http://a.particular.system/identifier"/>
<value value="123456"/>
</identifier>
</Patient>
Given that the identifier is the same, the patient resources are understood to mean that they describe the same patient. For this reason, systems SHOULD:
Following these practices will make for consistent identification of concepts and real-world entities across healthcare eco-systems. For example, medication orders can be represented as MedicationRequest and MedicationStatement. Some systems - primary sources - will provide the medication order as a MedicationRequest while other secondary systems will provide them as a MedicationStatement. Any system processing the resources will need to reconcile these, and the presence of consistent identifiers will considerably simplify the reconciliation process.
Note that this specification provides two other related methods by which common source derivation can be indicated:
derivationThe granularity of Provenance.entity.what[x] / Resource.meta.source is not fixed to a single resource - multiple resources can be derived from a single source entity (e.g. a single CDA document), so applications need to be careful assuming that matching entity source information means that the resources are identifying the same real-world concept.
A reference to a custom agreement that describes how the resource is being used (e.g. an implementation guide) that was followed when the resource was constructed, where the implementation guide must be known and understood in order to safely processing the content.
Asserting this rule set restricts the content to be only understood by a limited set of trading partners. This inherently limits the usefulness of the data in the long term, and should be avoided where possible. However, the existing health eco-system is highly fractured, and not yet ready to define, collect, and exchange data in a generally exchangeable sense.
Note that resources are almost always constructed following some custom agreement.
Best practice - which is recommended throughout the conformance resources - is that
such agreements make all knowledge about the content of the resource explicit in
the content of the resource; if custom agreements follow this advice, and declare
their extensions as required, then it is not necessary to understand the agreement
in order to safely process the resource content. For this reason, use of
implicitRules is rare.
Each resource may have a language element that specifies the base language of the content using a code defined in BCP 47 .
The language element is provided to support indexing and accessibility (e.g. text-to-speech use the language tag).
If a language is specified, it should also be specified on the Narrative Text. The html language tag in the narrative is used when processing the narrative. The language tag on the resource is provided so that applications processing the data in the resource can specify the language of any alternate presentations generated from the data.
There is no default language, though one may be inferred from the context of use. Not all of the content of the resource has to be in the specified language. Multiple languages can be supported.
Any valid language code as defined in BCP 47 is valid. The
language code system is complex, with parts for Primary Language, Script, Region, and other variants
and extensions. In order to simplify implementations, the language element has a preferred binding
to an enumerated list of common language codes encountered in applications, with translations, and also
a maximum binding of any language; this allows most applications to simply use a look up table, without
preventing the use of any language code.
Each resource contains an element "meta", of type "Meta", which is a set of metadata that provides technical and workflow context to the resource. The metadata items are all optional, though some or all of them may be required in particular implementations or contexts of use.
| Metadata Item | Type | Usage |
|---|---|---|
| versionId (0..1) | id | Changes each time the content of the resource changes. Can be referenced in a resource reference.
Can be used to ensure that updates are based on the latest version of the resource.
The version can be globally unique, or scoped by the Logical Id of the resource. Version identifiers are generally either a serially incrementing id scoped by the logical id, or a uuid, though neither of these approaches is required. There is no fixed order for version ids - clients cannot assume that a versionId that comes after another one either numerically or alphabetically represents a later version. The same versionId can never be used for more than one version of the same resource. On the RESTful API: On receiving an update, patch, or other FHIR operation that impacts meta, the server SHALL update this item to the current value, or remove it. Note that servers SHOULD support versions, but some are unable to |
| lastUpdated (0..1) | instant | If populated, this value changes each time the content of the resource
changes. It can be used by a system or a human to judge the currency of the resource content.
Note that version aware updates do not depend on this element. Note that
a timezone code extension may be present on Meta.lastUpdated.
If present, the timezone code applies to the server copy of the resource, and not necessarily to other
time related elements within the resource even if the timezone offsets are the same.
On the RESTful API: On receiving a create, update, patch, or other FHIR operation that impacts meta, the server SHALL update this item to the current time on the server |
| source (0..1) | uri | A uri that identifies the source system of the resource. This provides a minimal amount of Provenance
information that can be used to track or differentiate the source of information in the resource. The source
may be another resource, or it may be a more abstract or general identifier, or identify another FHIR server, end-point, document, message, database, etc.
The exact use of the source (and the implied Provenance.entity.role) is left to implementer discretion.
Only one nominated source is allowed; for additional provenance details, a full Provenance resource should be used.
On the RESTful API: On receiving a create, update, patch, or other FHIR operation that impacts meta, the server SHOULD generally leave this unchanged, unless applicable business rules, along with available provenance, dictate otherwise |
| profile (0..*) | canonical | An assertion that the content conforms to a resource profile (a StructureDefinition). See Extending and Restricting Resources for further discussion.
Can be changed as profiles and value sets change or the system rechecks conformance. The profile can be used to
indicate which version(s) of FHIR a resource conforms to.
On the RESTful API: On receiving a create, update, patch, or other FHIR operation that impacts meta, the server MAY elect to remove invalid claims, SHOULD retain claims that are correct or untested, and MAY add additional claims it believes are valid |
| security (0..*) | Coding | Security labels applied to this resource. These tags connect resources in specific ways to
the overall security policy and infrastructure. Security tags can be updated when the resource changes, or whenever the security sub-system chooses to.
On the RESTful API: On receiving a create, update, patch, or other FHIR operation that impacts meta, the server SHOULD preserve the labels unless applicable business rules dictate otherwise |
| tag (0..*) | Coding | Tags applied to this resource. Tags are used to relate resources to process and workflow. Applications are not required to consider
the tags when interpreting the meaning of a resource.
On the RESTful API: On receiving a create, update, patch, or other FHIR operation that impacts meta, the server SHOULD preserve the labels unless applicable business rules dictate otherwise |
| FHIR Infrastructure | Maturity Level: 5 | Standards Status: Normative |
See also Base Definition, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions
Structure
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| ΣN | Element | Metadata about a resource Elements defined in Ancestors: id, extension | ||
| Σ | 0..1 | id | Version specific identifier | |
| Σ | 0..1 | instant | When the resource version last changed | |
| Σ | 0..1 | uri | Identifies where the resource comes from | |
| Σ | 0..* | canonical(StructureDefinition) | Profiles this resource claims to conform to | |
| Σ | 0..* | Coding | Security Labels applied to this resource Binding: All Security Labels (Extensible) | |
| Σ | 0..* | Coding | Tags applied to this resource Binding: Common Tags (Example) | |
UML Diagram (Legend)
XML Template
<meta xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <versionId value="[id]"/><!-- 0..1 Version specific identifier --> <lastUpdated value="[instant]"/><!-- 0..1 When the resource version last changed --> <source value="[uri]"/><!-- 0..1 Identifies where the resource comes from --> <profile><!-- 0..* canonical(StructureDefinition) Profiles this resource claims to conform to --></profile> <security><!-- 0..* Coding Security Labels applied to this resource --></security> <tag><!-- 0..* Coding Tags applied to this resource --></tag> </meta>
JSON Template
{
// from Element: extension
"versionId" : "<id>", // Version specific identifier
"lastUpdated" : "<instant>", // When the resource version last changed
"source" : "<uri>", // Identifies where the resource comes from
"profile" : ["<canonical(StructureDefinition)>"], // Profiles this resource claims to conform to
"security" : [{ Coding }], // Security Labels applied to this resource
"tag" : [{ Coding }] // Tags applied to this resource
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extension fhir:versionId [ id ] ; # 0..1 Version specific identifier fhir:lastUpdated [ instant ] ; # 0..1 When the resource version last changed fhir:source [ uri ] ; # 0..1 Identifies where the resource comes from fhir:profile ( [ canonical(StructureDefinition) ] ... ) ; # 0..* Profiles this resource claims to conform to fhir:security ( [ Coding ] ... ) ; # 0..* Security Labels applied to this resource fhir:tag ( [ Coding ] ... ) ; # 0..* Tags applied to this resource ]
Changes since Release 3
Structure
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| ΣN | Element | Metadata about a resource Elements defined in Ancestors: id, extension | ||
| Σ | 0..1 | id | Version specific identifier | |
| Σ | 0..1 | instant | When the resource version last changed | |
| Σ | 0..1 | uri | Identifies where the resource comes from | |
| Σ | 0..* | canonical(StructureDefinition) | Profiles this resource claims to conform to | |
| Σ | 0..* | Coding | Security Labels applied to this resource Binding: All Security Labels (Extensible) | |
| Σ | 0..* | Coding | Tags applied to this resource Binding: Common Tags (Example) | |
XML Template
<meta xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <versionId value="[id]"/><!-- 0..1 Version specific identifier --> <lastUpdated value="[instant]"/><!-- 0..1 When the resource version last changed --> <source value="[uri]"/><!-- 0..1 Identifies where the resource comes from --> <profile><!-- 0..* canonical(StructureDefinition) Profiles this resource claims to conform to --></profile> <security><!-- 0..* Coding Security Labels applied to this resource --></security> <tag><!-- 0..* Coding Tags applied to this resource --></tag> </meta>
JSON Template
{
// from Element: extension
"versionId" : "<id>", // Version specific identifier
"lastUpdated" : "<instant>", // When the resource version last changed
"source" : "<uri>", // Identifies where the resource comes from
"profile" : ["<canonical(StructureDefinition)>"], // Profiles this resource claims to conform to
"security" : [{ Coding }], // Security Labels applied to this resource
"tag" : [{ Coding }] // Tags applied to this resource
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extension fhir:versionId [ id ] ; # 0..1 Version specific identifier fhir:lastUpdated [ instant ] ; # 0..1 When the resource version last changed fhir:source [ uri ] ; # 0..1 Identifies where the resource comes from fhir:profile ( [ canonical(StructureDefinition) ] ... ) ; # 0..* Profiles this resource claims to conform to fhir:security ( [ Coding ] ... ) ; # 0..* Security Labels applied to this resource fhir:tag ( [ Coding ] ... ) ; # 0..* Tags applied to this resource ]
Note that the RESTful API defines some Operations that provide direct read and write access to the meta element.
There are 3 different versions of interest for a resource:
Record (Resource) Version
All resources are conceptually versioned, and each resource sits at the head of a linear list of past versions. The past versions are superseded by the current version, and only available for audit/integrity purposes. The current version is e.g. http://acme.org/fhir/ResourceType/id123, and a past version would be http://acme.org/fhir/ResourceType/id123/_history/v2.
Note that there's no requirement for servers to keep a history. The history interaction is provided for where this is an appropriate service to provide. However, whether a server keeps them or not, past versions are dead and gone. The current version of the resource is in the Resource.meta.versionId. For a value set this would be:
<ValueSet>
<meta>
<versionId value="v2"/>
</meta>
</ValueSet>
The versionId changes every time the server updates the resource and writes a new version over the top of an existing one.
Business Version
Some resources have another version marker in them. For instance, ValueSet has another version in it:
<ValueSet> <url value="http://acme.com/fhir/ValueSet/example"/> <version value="2.0"/> </ValueSet>
This says that this is version 2.0 of the 'example' value set. This is the business version of the value set, the one that humans get involved with. These 2 versions elements have quite different lifecycles. To illustrate, take these cases:
The version of resource SHOULD change every time some non-significant change is made. Exactly what change
constitutes 'significant' depends on context, and is not specified here. Note, though, that it is possible
to change elements such as status and date without changing the version, such as
when marking a past version as retired. In general, any other changes should be associated
with a change in version.
The Semantic Versioning specification recommend that versions be represented in three parts using the form MAJOR.MINOR.PATCH where,
for the kind of artefacts described in this specification:
For the kind of resources that have canonical URLs, this specification
recommends that implementers follow the Semantic Versioning principles, but does not require this.
Implementers should consider, however, making the MAJOR version part of the canonical URL
rather than putting it in [Resource].version. So instead of this:
{
"resourceType" : "ValueSet",
"url" : "http://example.org/fhir/ValueSet/blah",
"version" : "2.1.1"
}
implementers should instead consider:
{
"resourceType" : "ValueSet",
"url" : "http://example.org/fhir/ValueSet/blah2",
"version" : "1.1"
}
The principle advantage is that other artefacts that reference the first artefact can do so by major version:
"binding" : {
"valueSet" : "http://example.org/fhir/ValueSet/blah2"
}
The alternative - not having the major version in the URL - means that version dependencies must be managed by some other method (e.g. managing a set of resources with specific versioned references via an Implementation Guide).
There is no single best practice here; the correct choice depends on many factors outside the scope of this specification.
For business versions in canonical resources, the busines version SHOULD NOT contain a #
character, since the version appears in the URL, and the # has special meaning in a URL.
If the version does contain a #, then it SHALL be escaped properly when used in a URL
as specified by Canonical References.
FHIR Version
All resources always have a FHIR version against which they were written. Note, however, that resources may be valid against multiple different FHIR versions, and this becomes progressively more likely as the maturity of the resource progresses.
The version is often not stated explicitly in the resource; it is controlled by the context. See Managing Multiple FHIR versions for further information.
These 3 metadata attributes are part of the resource, but are never used to keep information that needs to be understood when interpreting the content of a resource; their function is limited to finding and controlling access to the resource, and connecting resources to technical or clinical workflow.
Tags are used to associate additional operational information with the Resources, such as workflow management. A typical use of tagging would be to maintain an informal list of resources that need review.
In a general tag, the coded concept may be a reference to a
healthcare vocabulary, including ones defined in this specification, or vocabularies such
as those defined by HL7 for other purposes (e.g. HL7 V2 and HL7 v3
/CDA
), LOINC, or SNOMED CT.
Alternatively, the concept may be one defined by the implementation in the local context.
The list of tags on a resource is a set, where each tag is unique based on the
system+code combination.
A profile assertion represents a claim that the resource conforms to the identified StructureDefinition, which makes rules about what content is allowed to be in a resource. In a profile tag, the term is a URL that references an identified StructureDefinition resource.
It's always possible to determine whether a resource conforms to any profile simply by testing it against the profile (the validation tools provide the functionality to perform this test in a variety of contexts). However there are several circumstances where simply examining whether a resource conforms to a particular profile as needed is impractical:
Profile Tags serve these use cases - a client/creator of a resource can tag the resource with an assertion that the resource conforms to a particular structure definition. The server/receiver of the resource can choose to take this assertion at face value, or to assist in locating the correct StructureDefinition against which to validate the resource.
Note: resources can conform to multiple profiles at once. A resource can conform to a profile without ever being labeled that it does, or a resource may falsely claim to conform to a profile. For this reason, applications processing resources SHOULD always depend on the contents of the resource when processing them, and/or check resources against the StructureDefinitions directly rather than relying the existence of profile tags for meaning. Profile Tags are provided as a method of finding resources that conform to a particular StructureDefinition, not statements of meaning about the resource.
Many trading partner agreements will make rules about what claims can be made and when they must be tested, which will make the profile assertion more reliable.
The list of profiles on a resource is a set, where each profile is unique based on the value of the URI.
A security label is attached to a resource to provide specific security metadata about the information in the resource. For further information, see Security Labels.
Note, it is valid to create two security labels with the same (system+code) but different
.display or .version. Furthermore, .display or .version are not
taken into account when evaluating security labels.
When a resource is updated (e.g. on the RESTful interface), servers generally follow this pattern:
However, in some cases, an update may invalidate existing tags. Servers may update or remove previously existing recognized tags if this is known to be appropriate. A client can retrieve the current tags using the $meta operation.
The Maturity level documentation has moved.
Search parameters defined by this abstract resource for all descendents. See Searching for more information about searching in REST, messaging, and services.
| Name | Type | Description | Paths |
| _content | special | Search on the entire content of the resource | |
| _filter | special | Filter search parameter which supports a more sophisticated grammar for searching. See [documentation](search_filter.html) for further details | |
| _has | special | Provides limited support for reverse chaining - that is, selecting resources based on the properties of resources that refer to them (instead of chaining where resources can be selected based on the properties of resources that they refer to). See the FHIR search page for further documentation | |
| _id | token | Logical id of this artifact | Resource.id |
| _in | reference | Allows for the retrieval of resources that are active members of a CareTeam, Group, or List | Resource.id |
| _language | token | Language of the resource content | Resource.language |
| _lastUpdated | date | When the resource version last changed | Resource.meta.lastUpdated |
| _list | special | Allows for the retrieval of resources that are referenced by a List resource or by one of the pre-defined functional lists | |
| _profile | reference | Profiles this resource claims to conform to | Resource.meta.profile (StructureDefinition) |
| _query | special | A custom search profile that describes a specific defined query operation | |
| _security | token | Security Labels applied to this resource | Resource.meta.security |
| _source | uri | Identifies where the resource comes from | Resource.meta.source |
| _tag | token | Tags applied to this resource | Resource.meta.tag |
| _text | string | Text search against the narrative | |
| _type | special | A resource type filter |
FHIR ®© HL7.org 2011+. FHIR R5 hl7.fhir.core#5.0.0 generated on Sun, Mar 26, 2023 15:23+1100.
Links: Search |
Version History |
Contents |
Glossary |
QA |
Compare to R4
|
Compare to R4B
|
|
Propose a change