Metadata in FHIR

Last week, I implemented the $meta, $meta-add and $meta-delete operations in Ewout’s FHIR .NET API . This gave me the idea to write a blogpost about how FHIR metadata has changed between DSTU-1 and the current version of FHIR (v0.4.0).

DSTU-1

In DSTU-1 metadata consists of:

• LogicalD – Constant for the entire lifetime of the resource on the server.
• VersionID – Changes every time the resource changes.
• Last Modified Date – The date the resource was last modified.
• Tags –  Expressions of out-of-band data, for example example a profile tag, which stated to which profile(s) the resource conformed to, or a security tag where you could put a security label on your resource see: http://hl7.org/implement/standards/fhir/security-labels.html.

In DSTU-1 the metadata was positioned outside the resource, in an “envelope” that also contained the resource. On the wire, this data was put into headers (the Category and Content-Location headers to be precise).

What’s changed?

Now let’s talk about DSTU-2:

In DSTU-2 the metadata moved from outside the resource to inside the resource. The LogicalId has moved into the Resource itself and there is now a “Meta” data type that can exist on every FHIR resource. This datatype looks like this:

And can be accessed like:

Patient.Meta.lastUpdated

As you can see, this data type has similar attributes as the metadata from DSTU-1. There is still versionID and lastUpdated. Deleted is new, and defines if a resource has been deleted or not. the profile and attribute data types were tags in DSTU-1, and have now become attributes of the Meta datatype.

Why this change?

The Metadata was moved inside the resource, because people expect it to be. If you want to fetch a resource from a FHIR server you would expect that you get a resource returned, not an envelope with metadata that also contains a resource.

You want to access the resource attributes like (DSTU-2):

[code language=”csharp”]
var pat = client.Read(“Patient/4″);
var name = pat.Name;
var id = pat.Id;
[/code]

NOT (DSTU1):

[code language=”csharp”]
var patEnvelope = client.Read(“Patient/4”);
var name = patEnvelope.resource.name;
[/code]

As well, other REST API’s had comparable data, but put the data side-by-side with the actual Resource data – no enveloping involved.

The $meta operation

The $meta operation can be used to access metadata, without getting the resource returned. The operation can be performed on different levels:

On server level:

POST http://fhir-dev.healthintersections.com.au/open/$meta

On resource type level:

POST http://fhir-dev.healthintersections.com.au/open/Patient/$meta

On these levels, the $meta operation is used to get a summary of all the labels that are in use across the system. The principle use for this operation is to support search e.g. what tags can be searched for. At these levels, the returned “meta” will not contain versionId, lastUpdated, deleted etc.

The operation can also be performed on instance level:

POST http://fhir-dev.healthintersections.com.au/open/Patient/1/$meta

And even on history level:

POST http://fhir-dev.healthintersections.com.au/open/Patient/1/_history/2/$meta

At these levels, the $meta operation returns the same meta as would be returned by accessing the resource directly. This can be used to allow a system to get access to the meta-information for the resource without retrieving the full resource itself, e.g. for security reasons.

$meta-add and $meta-delete

Using these $meta-add and $meta-delete operations we can easily change the metadata on the resources. These operations can be performed on the instance and history level:

POST http://fhir-dev.healthintersections.com.au/open/Patient/1/$meta-add 

OR

POST http://fhir-dev.healthintersections.com.au/open/Patient/1/_history/2/$meta-add

The metadata to be added or deleted is sent inside the body of the REST-call represented in a Meta datatype. This will look something like:

[code language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<Parameters xmlns=”http://hl7.org/fhir”>
<parameter>
<name value=”Meta”/>
<valueMeta>
<versionId value=”2″/>
<lastUpdated value=”2015-03-17T10:57:34+01:00″/>
<deleted value=”false”/>
<profile value=”http://hl7.nl/FHIR/Profile/DutchPatient”/>
<security>
<system value=”http://hl7.org/fhir/v3/ActCode”/>
<code value=”CEL”/>
<display value=”Celebrity”/>
</security>
</valueMeta>
</parameter>
</Parameters>
[/code]

Funny thing about this, is that these operations are currently the only one that can change a previous version of a resource. Note that changing the metadata does not change the version-id. This is because the content in meta does not affect the meaning of the resource, and the security labels (in particular) are used to apply access rules to existing versions of resources.

These new operations are currently in the newest version of the FHIR .NET API . However, we can’t test them yet, because no server has implemented the operations yet. I will post an update on this blogpost once we can get a proper response on the operations from one of the DSTU-2 FHIR servers.