R4 Draft for Comment

This page is part of the FHIR Specification (v3.2.0: R4 Ballot 1). 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 GroupMaturity Level: 2Ballot Status: Trial Use

This page and the RDF forms are jointly 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:

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 ];
]

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. Other MIME types: application/json-ld for the json-ld variant, and text/shex for the SHEX (RDF schemas)

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 its identity. Resources with no persistent identity (e.g. bundles from search results) have 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 one node labelled as a 'treeRoot' 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 with 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.

Note: this means that the rdf:list structure is not used.

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 has two parts: a literal string that contains the value, and, if applicable, one of the following schema types:

  • boolean
  • integer
  • decimal
  • base64Binary
  • dateTime
  • date
  • gYear
  • gYearMonth
  • time

The choice is made based on the types as specified for the primitive type. 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. However, it's very useful for an RDF processor if the RDF graph links to the target of the reference directly. This can be represented using the fhir:link property: 

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

The correct value for the fhir:link relationship must be determined by resolving the rules for resolving references for the various reference types to a literal URL that refers to the correct content in the local RDF context.

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 data type. 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 graph, it's very useful to make the implicit concept references in these Codings explicit using a rdf:type assertion ("a" in turtle): 

  fhir:Observation.code [
     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 rdf:type assertions can be made by any agent that knows how to convert from the code system to the correct ontological representation on the RDF context. 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 Experimental JSON-LD format

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 a single FHIR context: [url]/fhir.jsonld, where [url] is the URL of the applicable version (e.g. http://hl7.org/fhir/STU3). Implementers should use a version specific reference, not the current version (http://hl7.org/fhir) since the contents of this change as new full releases of FHIR are published)
  • Each resource has @type on every resource, since the resources are inherently polymorphic at the format level. In addition, the root node explicitly carries the property "role" : "fhir:treeRoot"
  • When parsing the JSON-LD format, applications should not use the literal JSON directly, but use the json-ld processed form. Any json-ld that results in the same content post-processing is considered conformant.
  • The JSON-LD format is derived from the RDF format, and processing the JSON-LD will result in the same set of triples as the turtle format, though there may be minor differences in the types of the nodes depending on the RDF library used.
  • For booleans and integers, JSON boolean and numbers are used. However for decimal values, a JSON string must be used.

STU Note: The definition of the JSON-LD format means that the FHIR specification defines two different JSON formats, each with a different purpose. 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 would prefer the JSON-LD format. On the other hand, defining two different JSON formats seems like a recipe for confusion. Feedback from implementers is welcome.

Feedback is welcome here .

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