Rdf - FHIR v1.8.0

STU3 Candidate

This page is part of the FHIR Specification (v1.8.0: STU 3 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

3.1 Resource Description Framework (RDF) Representation

FHIR Infrastructure

Work Group

Maturity Level: 0

Ballot Status: Draft

This page and the RDF forms are joinlty maintained by the HL7 FHIR project and the W3C Semantic Web Health Care and Life Sciences Interest Group .

FHIR resources can be represented as an RDF graph serialised in the Turtle format , or as JSON-LD . The RDF format is defined to assist the process of bridging between operational data exchange and formal knowledge processing systems. While the RDF form offers a fully functional representation of FHIR resources, it has different operational characteristics to the JSON and XML representations, and would be implemented for different reasons. Systems focused on operational exchange of data would not generally use choose to use RDF.

This page describes:

Representing FHIR resources in Turtle
The FHIR definitions as Turtle
How to exchange RDF using the RESTful API

3.1.1 Turtle Format for Resources

A FHIR resource is represented by a series of RDF triples. The Turtle representation for a resource is described using this format:

Turtle Template

[ a fhir:Observation; fhir:nodeRole fhir:treeRoot;
  # from Resource: id; meta; implicitRules; and language
  # from DomainResource: text; contained; extension; and modifierExtension
  fhir:Obervation.identifier [ Identifier ]; # 0..* Unique Id for this particular observation
  fhir:Obervation.status [ fhir:value "<code>" ]; # R!  registered | preliminary | final | amended +
  fhir:Obervation.code [ CodeableConcept ]; # 1..1 R!  Type of observation (code / type)
  fhir:Obervation.subject [ fhir:reference [ Patient|Group|Device|Location ] ]; # 0..1 Who and/or what this is about
  fhir:Obervation.encounter [ fhir:reference [ Encounter ] ]; # 0..1 Healthcare event during which this observation is made
  # effective[x]: 0..1 Clinically relevant time/time-period for observation. One of these 2:
    fhir:Obervation.effectiveDateTime [ fhir:value "<dateTime>" ];
    fhir:Obervation.effectivePeriod [ Period ];
]

Note: this is a placeholder for when the proper format is defined.

Using this format:

To build a valid Turtle instance of a resource, replace the contents of the property values with valid content as described by the type rules and content description found in the property value for each element
Relationship names are case-sensitive (though duplicates that differ only in case are never defined)
Relationships can appear in any order
Content within a resource is always represented with anonymous nodes - only resources can be identified
Nodes are never empty. If an element is present in the resource, it SHALL have properties as defined for its type, or 1 or more extensions
The R! denotes that a relationship is mandatory - it must be present (or in an array, at least one item must be present)
Note that this specification produces turtle that is nicely formatted and well laid out, but this is not required nor expected
The MIME-type for this format is text/turtle.

3.1.1.1 Representing resources

Each resource is represented as a set of RDF triples represented using the Turtle syntax. When a resource has a persistent identity (e.g. it can be found at a particular URL - usually a FHIR RESTful server), then that URL is it's identity. Resources with no persistent identity (e.g. bundles from search results) have the the identity of the root document - "<>" in turtle syntax.

Some resources can contain other resources. Given that the relationships can appear in any order, it cannot be assumed that the first encountered element represents the resource of interest that is being represented by the set of turtle statements. The focal resource - where to start when parsing - is the resource with the relationship fhir:nodeRole to fhir:treeRoot. if there is more than node in a set of turtle statements, it cannot be determined how to parse them as a single resource.

3.1.1.2 Representing Repeating Elements

Elements that can repeat are represented by a relationship

  fhir:index [n]

where [n] is a zero-based integer offset (ie.g the first element has an index of 0). Lists are never sparse; it is an error if there are missing items in the repeat sequence.

3.1.1.3 Representing Primitive Elements

Primitive elements - elements with a primitive type - are represented as regular nodes so that the elements extensions can be represented. The actual value of the primitive type is represented using the fhir:value predicate:

  fhir:value "[value]"^^xs:type

The value is always a literal string that contains the value, followed by a schema type as specified for the primitive type. The schema type is required, but may be omitted when the defalut value of xs:string is correct. Note that the correct schema type for a date/dateTime must be determined by inspecting the value of the date for precision.

The fhir:value property can never be empty. Either the relationship is absent, or it is present with at least one character of content. XHTML is represented as an escaped xs:string.

3.1.1.4 Representing References

A Reference element is representing using the same rules as above:

 fhir:Observation.subjectReference [
     fhir:Reference.reference [ fhir:value "Patient/example" ];
     fhir:Reference.display [ fhir:value "Example Patient" ];
  ];

This allows faithful round tripping of the resource between the Turtle format and the JSON and XML formats. But it's very useful for an RDF processor to be able to link to the target of the reference directly. This can be done using the fhir:link property:

 fhir:Observation.subjectReference [
     fhir:link <http://hl7.org/fhir/Patient/example>;
     fhir:Reference.reference [ fhir:value "Patient/example" ]
  ];

The fhir:link relationship can be added automatically as part of generating the resource representation, or it can be injected by a post-processor that knows how to convert the raw references into RDF-suitable references.

3.1.1.5 Representing Concepts

The same logic applies to the Coding and CodeableConcept data types. These are represented directly in turtle by serialising their properties as specified above:

  fhir:Observation.code [
     fhir:CodeableConcept.coding [
       fhir:index 0;
       fhir:Coding.system [ fhir:value "http://loinc.org" ];
       fhir:Coding.code [ fhir:value "29463-7" ];
       fhir:Coding.display [ fhir:value "Body Weight" ]     
    ];
    fhir:CodeableConcept.coding [
       fhir:index 1;
       fhir:Coding.system [ fhir:value "http://snomed.info/sct" ];
       fhir:Coding.code [ fhir:value "27113001" ];
       fhir:Coding.display [ fhir:value "Body weight" ]    
    ]
  ];

For reasoners using the RDF, it's very useful to make the implicit concept references in these Coding and CodeableConcept explicit using rdfs:type assertions:

  fhir:Observation.code [
     a loinc:29463-7;
     a sct:27113001;
     fhir:CodeableConcept.coding [
       fhir:index 0;
       a loinc:29463-7;
       fhir:Coding.system [ fhir:value "http://loinc.org" ];
       fhir:Coding.code [ fhir:value "29463-7" ];
       fhir:Coding.display [ fhir:value "Body Weight" ]     
     ];
     fhir:CodeableConcept.coding [
       fhir:index 2;
       a sct:27113001;
       fhir:Coding.system [ fhir:value "http://snomed.info/sct" ];
       fhir:Coding.code [ fhir:value "27113001" ];
       fhir:Coding.display [ fhir:value "Body weight" ]     
    ]
  ];

These type assertions can be make by any agent that knows how to convert from the code system to the correct ontological representation of that. Note that a few code systems have standard ontological representations, but many don't. Again, these assertions can be made by the serialiser, or injected by a post-processor.

3.1.1.6 Schema

FHIR uses ShEx for representing the turtle schema. See fhir.shex for definitions.

3.1.1.7 JSON-LD

As a by-product of the RDF format, a JSON-LD format is defined to represent exactly the same information as the Turtle format, but using the JSON-LD syntax. Some specific notes about the JSON-LD format:

There is an @context on every resource, since the resources are inherently polymorphic at the format level
There is a version problem with the definitions; the definitions are generated at the version specific end-point, but the context references are not version specific. Input on the issues associated with this is welcome

STU Note: The definition of the JSON-LD format means that the FHIR specification defines two different JSON formats. It seems unlikely that normal implementers will prefer the JSON-LD format over the other JSON format, since that is more dense, but there are other implementers who will use the JSON-LD format. On the other hand, defining two different JSON formats seems like a recipe for confusion. Feedback from implementers is welcome.

3.1.2 RDF Representation of FHIR

In addition to the basic representation of FHIR resources in turtle format, a Turtle representation of the FHIR infrastructure and definitions is also published, for the following purposes:

Providing the class definitions to support RDF based representation of resource instances
Supporting knowledge based analysis of the FHIR specification itself
Providing knowledge of use at run-time for converting between FHIR and other content models
Supporting reasoning across the information/terminology model boundary

The RDF definitions are published as a series of turtle files: RIM and FHIR. Note: these are out of sync with the serialization above; this will be fixed in the lead up to the Montreal connectathon.

3.1.3 Using RDF with the REST API

TODO