type: resourceresource: Resource

Resource

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. All the resources defined in this specification and elsewhere are specializations of this Resource type.

A resource is an entity that:

has a known identity by which it can be addressed
identifies itself as one of the types of resource defined in this specification or as described below
contains a set of structured data items as described by the definition of the resource type
has an identified version that changes if the contents of the resource change

Resources have multiple representations.

Boundaries and Relationships

The following optional elements and properties are defined for all resources:

An identity
Meta data
A base language
A reference to "Implicit Rules"

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.

Additional Resources defined Outside This Specification

This specification defines the base <%res-type-count%> resources that comprise the "FHIR resources". Additional resources may be defined in other specifications, and used as part of the FHIR framework. For those implementers who wish to use other resources, or find that they need to, the following rules apply:

Additional Resources to be used like this SHALL be registered with HL7
Unapproved resources SHALL NOT be used
Registered and approved resources are given a name by HL7, and this is the name that must be used for the resource
All such registered and approved resources SHALL have a publicly available definition using a StructureDefinition published as part of an ImplementationGuide, published at the canonical URL. Note that the definitions will be reviewed for quality by HL7 prior to approval

HL7 publishes the list of approved resource at (somewhere?) (todo: this needs further work, but at this time the functional list is published here: IG Registry). If you wish to register such a resource, the process starts by making a proposal here.

These sections contain information about how additional resources work in the various places that they may be encountered through this specification:

Moving Additional Resources to FHIR Core

Additional resources are all expected to eventually migrate to this specification once they are stable.

Generally, the process for moving an Additional Resource to core is:

The responsible WG/WGs need to request moving into core.
FMG needs to approve moving into core (criteria TBD by FMG).
The resource will be added to the next ballot of FHIR core.
The resource will be officially available when the milestone release that includes it is published.
Concurrently with that FHIR Core publication, the status of the 'additional' definition should be updated so that it is deprecated and then eventually removed
Once the resource has been moved to core, the resourceDefinition element defined for XML and JSON is allowed to remain present, but SHOULD NOT be added. If it is present, the version SHALL be correct with regards to the published core FHIR version

Notes

Resource Identity

There are two different ways to identify a resource:

By a "Location" URL that identifies where it can be accessed (based on the "Logical ID"). This location will be changed as it is copied/moved around
By some inherent identifier ("Business Identifier" or "Canonical URL") that is part of the resource and remains fixed as it is copied/moved around

Logical ID

Each resource has an id element which contains the "logical id" of the resource assigned by the server responsible for storing it. Resources almost always have a known logical id except for a few special cases:

when a new resource is being sent to a server to assign a logical id in the create interaction
A search response or history response Bundle
Any resource (including Parameters) passed as input to an operation that was created purely for use as operation input and is not retained/persisted by the operation invoker
Any resource (including Parameters) received as output from an operation that was generated as part of performing the operation and is not retained/persisted by the operation performer.
A resource created for exchange outside the RESTful context (e.g. a document sent by email or FTP), including some types of messaging exchanges.

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.

[%dragons-start%]

FHIR Version Conversion Issue

If a system does not have server-unique (as opposed to resource-unique) logical ids for resources and are using Basic to do cross-version representations using Basic, be aware that ID collisions are possible and problematic. Possible mitigations could include prefixing/suffixing ids, using a common id namespace for resources subject to being exposed as Basic, or moving to globally unique logical ids. Note that ids SHOULD be consistent regardless of the FHIR version used to expose the data.

[%dragons-end%]

Identifier Categories

In general, identifiers are sometimes categorised into one of three categories: Business, informational, and instance.

a business identifier that uniquely identifies a singleton thing in the real-world, e.g. a patient Jane Dupont, a drug Amoxycillin, etc., and if there are records about this thing inside systems, such an id would be one way to search for such record(s)
an informational identifier that is guaranteed unique for every informational entity known inside systems, including entities that appear to be not directly related to real-world singleton entities (e.g. each med. rec. event on some patient's Rx list), aka things that don't have business identifiers;, aka things that are 'just information'
an instance identifier, guaranteed to be unique for any distinguishable instance of each logical informational entity (i.e. doesn't change for exact copies, but does change as soon as changes are made)

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.

"Business" Identifiers

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.

Canonical URLs

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:

Other Additional Resources have canonical urls.

Consistent Resource Identification

Business Identifiers are the preferred basis to recognize the same content on different systems. For example:

GET http://a.company.example.com/Patient/23

GET http://other.company.example.com/fhir/Patient/5860200e-0ee3-42f5-8095-506e18dc9ca2

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:

Only assign identifiers to resources when they uniquely identify the real-world entity that the resources match (e.g. do not use account numbers as patient identifiers when multiple different patients share the same account number)
Preserve identifiers as much as possible and not throw them away. Even if the identifiers are not useful to the system itself, they are likely to be useful to downstream consumers
When serving resources, use consistent identifiers from the master persistent store where ever possible (e.g. when a resource is created from a primary record, populate the identifier, and store the identifier somewhere so the same identifier is used next time)

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:

Provenance - resources that have provenance statements where Provenance.entity.what[x] refers to the same source, and the .entity.role is derivation
Resource.meta.source - two resources that have the same source

The 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.

Implicit Rules

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.

Language

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.

Resource Metadata

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. <br/> 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 data source 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. <br/> 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. <br/> 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. <br/> 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. <br/> 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

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

Changes from both R4 and R4B

| Meta |

No Changes

| | --- | --- |

See the Full Difference for further information

Structure

Name	Flags	Card.	Type	Description & Constraints
Meta	Σ N		Element	Metadata about a resource

| | <br/> doco Documentation for this format |

UML Diagram (Legend)

XML Template

<meta xmlns="http://hl7.org/fhir">

<versionId value="[id]"/> <lastUpdated value="[instant]"/> <source value="[uri]"/> <profile></profile> <security></security> <tag></tag> </meta>

JSON Template

Turtle Template

@prefix fhir: http://hl7.org/fhir/ .

[

from Element: Element.extension

Changes since Release 3

Changes from both R4 and R4B

| Meta |

No Changes

| | --- | --- |

See the Full Difference for further information

StructureDefinition

Elements (Simplified)

Resource [0..*]: - Base Resource
Resource.id [0..1]: http://hl7.org/fhirpath/System.String Logical id of this artifact
Resource.meta [0..1]: Meta Metadata about the resource
Resource.implicitRules [0..1]: uri A set of rules under which this content was created
Resource.language [0..1]: code required:all-languages Language of the resource content

Mappings

Resource Mappings — 1 mapping entries

Implementation Guide

implementationguide-Resource-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="Resource-core"/>
  <version value="0.01"/>
  <name value="ResourceHL7Extensions"/>
  <title value="Resource  H L7  Extensions"/>
  <status value="draft"/>
  <date value="1970-01-01T10:00:00+10:00"/>
  <publisher value="HL7"/>
  <description value="Defines common extensions used across multiple different resources"/>
</ImplementationGuide>

Operations

convert — Convert from one form to another — This operation takes a resource in one form, and returns to in another form.
graphql — Execute a graphql statement — Execute a graphql statement on a since resource or against the entire system.
validate — Validate a resource — The validate operation checks whether the attached content would be acceptable either generally, as a create, an update or as a delete to an existing resource.

Full Operations

Resource Packs

list-Resource-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="Resource-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/Resource-core"/>
    </item>
  </entry>
</List>

Search Parameters

_content — special — Search on the entire content of the resource — -
_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
_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
_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 — -
_type — special — A resource type filter — -
_filter — special — Filter search parameter which supports a more sophisticated grammar for searching. See documentation for further details — -

Full Search Parameters

Resource

Introduction

Scope and Usage

Boundaries and Relationships

Additional Resources defined Outside This Specification

Moving Additional Resources to FHIR Core

Notes

Resource Identity

Logical ID

FHIR Version Conversion Issue

Identifier Categories

"Business" Identifiers

Canonical URLs

Consistent Resource Identification

Implicit Rules

Language

Resource Metadata

Meta

from Element: Element.extension

from Element: Element.extension

StructureDefinition

Elements (Simplified)

Mappings

Implementation Guide

implementationguide-Resource-core.xml

Operations

Resource Packs

list-Resource-packs.xml

Search Parameters