This page is part of the FHIR Specification (v0.11: DSTU 1 Ballot 3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions
A resource is an entity that:
Resources have multiple representations. A resource is valid if it meets the above rules, and is represented in either XML or JSON according to the rules defined in this specification. Other representations are allowed, but are not described by this specification.
This specification defines a series of different resource types 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 resources have the following aspects:
The contents of the base resource from which all other resources derive are:
<[Name] xmlns="http://hl7.org/fhir"> <extension><!-- 0..* Extension See Extensions --></extension> <language value="[code]"/><!-- 0..1 Human language of the content (BCP-47) --> <text><!-- 1..1 Narrative Text summary of resource content, for human interpretation --></text> <contained><!-- 0..* Resource Contained Resources --></contained> <!-- Defined Data Elements for Resource --> </[Name]>
These elements must always appear in this order. These basic elements shared by all resources come first in order to support consistent definitions for schema and UML derived code.
The optional language element specifies the base language of the resource using the codes defined in BCP 47. Note that not all the content of the resource has to be in the language. If a language is specified, it should also be specified on the Narrative Text.
The language element is provided to support indexing and accessibility (e.g. text-to-speech use the language tag). The html language tag in the narrative is used when processing the narrative. The language tag on the resource is provided for use to specify the language of alternate presentations generated from the data in the resource
The metadata properties are key aspects of the resource and how it behaves. For implementation reasons, these are represented outside the resource:
| Metadata Item | Type | Usage |
|---|---|---|
| Logical Id | id | The identity of the resource. Resources always have a known identity and it is constant for the entire lifetime of the resource. Resource identification is discussed elsewhere |
| Version Id | 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. Since version ids must be unique within the scope of a single resource, they are generally either a serially incrementing id scoped by the logical id, or a uuid, though neither of these approaches is required |
| Last Modified Date | instant | Changes each time the content of the resource changes. Can be used by a system or a human to judge the currency of the resource content. |
Note that the version id changes any time the resource changes, and so does the last modified date. The Version Id is more useful for managing concurrency issues and version specific references because of the inherent uncertainties and precision limits associated with date times. The Last Modified Date is useful for a human to ascertain the logical currency of the information in the resource.
In any environment where the resources are used, the technical details of how these metadata elements are represented will need to be resolved. For further details, see Implementation Details, which also contains a discussion of how resource identity is maintained.
Resource ids are case sensitive. Ids are always opaque, and systems need not and should not attempt to determine their internal structure. However the id is represented, it must always be represented in the same way in resource references and URLs. Ids can be up to 36 characters long, and contain any combination of ASCII letters, numerals, "-" and ".".
The contents of the resource and the formats used to represent it must conform to the rules described in this specification. Because of its general nature and wide applicability, the rules made in this specification are generally loose compared to the rules suitable for particular use cases. This specification provides a conformance layer that implementers and national/regional programs can use to provide a computable statement about how the resources and their exchange paradigms are used to solve particular use cases. This conformance layer is delivered through use of the Conformance and Profile resources.
The specification also provides a number of technical resources that can assist with enforcing conformance to this base specification:
Note that none of these are able to check complete conformance to this specification.
The data elements defined resources and data types have 4 properties that are directly related to conformance: Cardinality, Is-Modifier, Must-Support, and Cardinality. These interact to place conformance requirements on implementations.
All elements defined in FHIR have a cardinality as part of their definition - a minimum number of required appearances, and a maximum number. This number specifies the number of times the element may appear in any instance of the resource type. This specification only defines the following cardinalities: 0..1, 0..*, 1..1, and 1..*. Profiles that describe specific use cases may use other values for cardinality within the limits of the cardinality defined by the resource.
Note that when present, elements cannot be empty - they must have either a value attribute, child elements, or extensions.
In this specification, very few elements have a minimum cardinality of 1. Resources are used in many contexts, often quite removed from their primary use case, and sometimes even basic information is sometimes very incomplete. For this reason, the only elements that have a minimum cardinality of 1 are those where they are necessary to any understanding of the element that contains them. The minimum cardinalities should not be taken as a guide to which elements are expected to be present in any particular use of the resource.
For elements that have cardinality > 1, the order in which they appear may have meaning. Unless the element definition (either in this specification or the extension) defines a meaning to the order explicitly, the meaning of the order is not defined, and implementations are allowed to reorder the elements. Note that you cannot define a meaning for the order of the elements in a profile. When there is no definition of the meaning of the order, implementations that need to choose a single element from a list of elements for some use must do so based on the semantics of the content of the elements that repeats. Profiles and Implementation guides may often make rules about this selection process.
Is-Modifier is a boolean property that is assigned when an element is defined, either as part of the base resource contents in this specification, or when profiles declare extensions. An element is labelled "Is-Modifier = true" if the value it contains may change the interpretation of other elements or the resource as a whole. Typical examples of elements that are labelled "Is-Modifier" are elements such as "status", "active", or "certainty". The value of Is-Modifier cannot be changed when element usage is described in a Resource Profile. When an element is labelled as Is-Modifier, the documentation must be clear about why it is a modifier, and/or which elements the element may modify.
Generally, elements labelled "Is-Modifier = true" also have a minimum cardinality of 1, to introduce certainty in their handling. If the value of such an element is not explicit in the instance, or known by the context, the resource cannot be safely understood. Irrespective of the minimum cardinality, implementations producing resources SHALL ensure that appropriate values for isModifier elements are provided. Is-Modifier elements SHALL be represented in the narrative summary of the resource.
Implementations processing resources SHALL understand the impact of the element when they process the resource. Implementations are not required to "support" the element in any meaningful way - they may achieve this by rejecting instances that contain values outside those they support (for instance, an application may refuse to accept observations with a reliability != "ok"). Alternatively, implementations may be able to be sure, due to their implementation environment, that such values will never occur. However applications SHOULD always check the value irrespective of this.
Servers and background processes that move resources around are not "processing the data of the resource", and these applications are not required to check for unknown extensions. Any process that copies data out of a resource for use in another context (display to a human, decision support, exchange in another format that doesn't support extensions) is processing the data.
Labelling an element Must-Support means that implementations that produce or consume resources must provide "support" for the element in some meaningful way. Exactly what this means is impossible to describe or clarify as part of the FHIR specification.
For this reason, the specification itself never labels any elements as must-support. This is done in Resource Profiles, where the profile labels an element as mustSupport=true. When a profile does this, it must also make clear exactly what kind of "support" is required, as this can mean many things.
Note that an element that has the property IsModifier is not necessarily a "key" element (e.g. one of the important elements to make use of the resource), nor is it automatically mustSupport - however both of these things are more likely to be true for IsModifier elements than for other elements.
The following rules will apply once the specification becomes a full normative specification. These rules ensure that implementations may process the content of the resources safely while exchanging data between applications using different versions of FHIR. However during the period of trial use of the specification, HL7 may make changes outside the limitations described here in response to discovered issues in the specification. Applications may wish to use resource tags to help manage this during the period of trial use.
There is no explicit version marker in the resource content. Once normative, subsequent versions of this specification may introduce new elements and/or content at any point in the resource contents, but the path and meaning of existing data elements will not be changed. Any value set or code list may be revised to include additional cods
Each binding to a value set or code system indicates whether the value list automatically grows as new codes are defined, whether the list may be extended in future versions of the specification, or whether the list cannot be changed at all in future versions.
The conformance layer (Conformance and Profile) have mandatory properties declaring the FHIR specification version, and these may be used to determine which version of FHIR an implementation is using.
In a typical scenario, mixed versions may need to exist, so applications SHOULD ignore elements that they do not recognize unless they are extensions with a isModifier element with value="true". However, in a healthcare context, many application vendors are unwilling to consider this approach because of concerns about clinical risk or technical limitations in their software (i.e. schema based processing). Applications are not required to ignore unknown elements, but must declare whether they will do so in their conformance statements using the acceptUnknown element.
Additional discussion on interversioning issues can be found here: http://wiki.hl7.org/index.php?title=FHIR_interversion_compatibility.
Additional documentation.