2.28 Base Resource Definitions

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.

• Structure
• UML
• XML
• JSON
• Turtle
• R2 Diff
• All

Structure

Name	Flags	Card.	Type	Description & Constraints
Meta	Σ		Element	Metadata about a resource Elements defined in Ancestors: id, extension
versionId	Σ	0..1	id	Version specific identifier
lastUpdated	Σ	0..1	instant	When the resource version last changed
profile	Σ	0..*	uri	Profiles this resource claims to conform to
security	Σ	0..*	Coding	Security Labels applied to this resource All Security Labels (Extensible)
tag	Σ	0..*	Coding	Tags applied to this resource Common Tags (Example)
Documentation for this format

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 -->
 <profile value="[uri]"/><!-- 0..* Profiles this resource claims to conform to -->
 <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
  "profile" : ["<uri>"], // 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:Meta.versionId [ id ]; # 0..1 Version specific identifier
  fhir:Meta.lastUpdated [ instant ]; # 0..1 When the resource version last changed
  fhir:Meta.profile [ uri ], ... ; # 0..* Profiles this resource claims to conform to
  fhir:Meta.security [ Coding ], ... ; # 0..* Security Labels applied to this resource
  fhir:Meta.tag [ Coding ], ... ; # 0..* Tags applied to this resource
]

Changes since DSTU2



Meta	No Changes

See the Full Difference for further information

Structure

Name	Flags	Card.	Type	Description & Constraints
Meta	Σ		Element	Metadata about a resource Elements defined in Ancestors: id, extension
versionId	Σ	0..1	id	Version specific identifier
lastUpdated	Σ	0..1	instant	When the resource version last changed
profile	Σ	0..*	uri	Profiles this resource claims to conform to
security	Σ	0..*	Coding	Security Labels applied to this resource All Security Labels (Extensible)
tag	Σ	0..*	Coding	Tags applied to this resource Common Tags (Example)
Documentation for this format

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 -->
 <profile value="[uri]"/><!-- 0..* Profiles this resource claims to conform to -->
 <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
  "profile" : ["<uri>"], // 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:Meta.versionId [ id ]; # 0..1 Version specific identifier
  fhir:Meta.lastUpdated [ instant ]; # 0..1 When the resource version last changed
  fhir:Meta.profile [ uri ], ... ; # 0..* Profiles this resource claims to conform to
  fhir:Meta.security [ Coding ], ... ; # 0..* Security Labels applied to this resource
  fhir:Meta.tag [ Coding ], ... ; # 0..* Tags applied to this resource
]

Changes since DSTU2

Meta	No Changes

See the Full Difference for further information

Note that the RESTful API defines some Operations that provide direct read and write access to the meta element.

2.28.3.3.1 Technical vs Business Versions

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>

That version changes every time the server updates the resource and writes a new version over the top of an existing one.

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:

1. A value set is posted to a server (POST [base]/ValueSet) with ValueSet.url = "http://acme.com/valuesets/example". This is identified as the 1st version of the value set (ValueSet.version = 1). When the server gets it, it assigns an identity e.g. ValueSet.id = x1, and ValueSet.meta.versionId = 1. Later, another user creates a revised version of the value set, and this is called version 2. It is committed to the server as an update (PUT [base]/ValueSet/x1).
   Now, ValueSet.url = http://acme.com/valuesets/example, ValueSet.id = x1, ValueSet.version = 2 and ValueSet.meta.versionId = 2
2. A value set is posted to a server (POST [base]/ValueSet) with ValueSet.url = "http://acme.com/valuesets/example". This is identified as the 1st version of the value set (ValueSet.version = 1). When the server gets it, it assigns an identity e.g. ValueSet.id = x1, and ValueSet.meta.versionId = 1. Then a typo is found in the definition, so this is fixed, but it's still v1 of the value set. This is PUT to [base]/ValueSet/x1. Now, ValueSet.url = http://acme.com/valuesets/example, ValueSet.id = x1, ValueSet.version = 1 and ValueSet.meta.versionId = 2.
   Later, another user creates a revised version of the value set, and this is called version 2. It is commmited to the server as an update (PUT [base]/ValueSet/x1). Now, ValueSet.url = http://acme.com/valuesets/example, ValueSet.id = x1, ValueSet.version = 2 and ValueSet.meta.versionId = 3
3. A value set is posted to a server (POST [base]/ValueSet) with ValueSet.url = "http://acme.com/valuesets/example". This is identified as the 1st version of the value set (ValueSet.version = 1). When the server gets it, it assigns an identity e.g. ValueSet.id = x1, and ValueSet.meta.versionId = 1. Later, another user creates a revised version of the value set, and this is called version 2. This time, as well as supporting this new version 2, there are production systems still using version 1, and both need to be valid on the value set server. So a new value set is created on the server (POST [base]/ValueSet) and is assigned the identiity 'x2'.
   Now, there are two different value sets, both with URL "http://acme.com/valuesets/example". One has ValueSet.id = x1, ValueSet.version = 1 and ValueSet.meta.versionId = 1 and the other has ValueSet.id = x2, ValueSet.version = 2 and ValueSet.meta.versionId = 1.

2.28.3.4 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 implemenation 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 through out the conformance resources - is that such agreements make all knowledge about the content of the resource explicit in the content of the resource (e.g. no default values in profiles); 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.

2.28.3.5 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).

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.

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.

2.28.3.6 Tags, Profiles, and Security Labels

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.

2.28.3.6.1 Tags

Tags are used to associate additional operational information with the Resources, including 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.

2.28.3.6.2 Profile Tags

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:

• A server searching a set of resources for ones that conform to a particular profile
• A receiver that has many profiles to choose when validating resource

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.

2.28.3.6.3 Security Labels

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.

The list of security on a resource is a set, where each tag is unique based on the system+code combination.

2.28.3.7 Updates to Tags, Profiles, and Security Labels

When a resource is updated (e.g. on the RESTful interface), servers generally follow this pattern:

• Merge existing and new tags
• Replace existing profile tags with new profile tags
• Merge existing and new security labels

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.

2.28.3.8 Further Information

• Conformance Rules
• Resource Definitions
• References between Resources
• Narratives
• Formats: XML, JSON
• Extensibility (Examples)
• Detailed Descriptions
• Inter-version Compatibility

2.28.3.9 Maturity Levels

The Maturity level documentation has moved.

2.28.4 Search Parameters

Common search parameters defined by this resource. See Searching for more information about searching in REST, messaging, and services.