FHIR Release 3 (STU) 4

This page is part of the FHIR Specification (v3.0.2: (v4.0.1: R4 - Mixed Normative and STU 3). ) in it's permanent home (it will always be available at this URL). 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 R4 R3 R2

3.1 2.6.4 Resource Description Framework (RDF) Representation

FHIR Infrastructure Work Group Maturity Level : 2 Ballot Standards 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 serialized 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 from 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:

Most of the major pieces of FHIR/RDF are now available in a complete enough form for developers to start trying them and providing feedback. Work still needed includes:

  • Improved documentation on using the RDF format
  • Reconciliation with the FHIR Ontology draft on W3C github
  • Tutorial materials on using FHIR/RDF with other ontologies and ShExMap to translate other RDF data (non-FHIR) to/from FHIR/RDF

2.6.4.1 Relationship between the RDF, FHIR, and ontologies

This page documents an RDF format that can be used to exchange FHIR data, on the basis that RDF is a universal information representation. Using RDF enables FHIR data to be used with RDF-aware applications to support inference, shared semantics across multiple standards and data formats, data integration, semantic data validation, compliance enforcement, SPARQL queries and other uses. Implementers using FHIR in this fashion should be aware of the relationship between the RDF format the wider use of ontologies.

The RDF format is based on the same abstract information model as the XML and JSON formats and carries the same information content. Resources are losslessly round-trippable between XML, JSON and RDF formats and data expressed in the RDF format corresponds closely to the XML and JSON formats in its look and feel. However, there are a few additional terms that may appear in the RDF format, which are explained below: fhir:nodeRole , fhir:treeRoot , fhir:value , fhir:index and fhir:concept . ShEx schemas are available that describe the RDF format.

In addition to defining the RDF format, this specification provides an associated ontology that provides formal definitions for the relationships that appear in the RDF format. Ontologies that were designed independently almost always have some impedance mismatch when attempting to use them together. Many of the ontologies in the medical and life sciences domain are designed to capture facts about the world for research, such as the fact that the mitral valve is a kind of heart valve. But FHIR was designed to support the day-to-day operations of healthcare providers exchanging electronic health records (EHRs), and in this context, the orientation has historically been different. When using FHIR/RDF with other ontologies, impedance differences are likely to show up in two main ways:

  • Records versus facts. FHIR is oriented toward recording who did what ("Dr. Jones diagnosed patient x with viral pneumonia") rather than stating absolute medical facts ("patient x has viral pneumonia").
  • Non-monotonicity. RDF was designed to be monotonic, whereas FHIR has a few design aspects that would be non-monotonic if they were interpreted directly in RDF. (Monotonicity means that new data cannot invalidate previous conclusions; non-monotonicity means that previous conclusions can be invalidated by new data.) For example, a modifier extension indicates that the surrounding element's meaning will likely be misunderstood if the modifier extension is not understood.

For both of these reasons, to maintain monotonicity in RDF, FHIR/RDF should not be directly interpreted as stating facts; transformations are required to remove or isolate non-monotonic elements and reconcile the records across time and perspective.

Application developers should also be aware that some FHIR data attributes have a major impact on the interpretation of the enclosing data element: the meaning of the enclosing element cannot be determined in isolation. For example, a status of 'entered-in-error' means that the resource was created accidentally and should be ignored for most purposes.

3.1.1 2.6.4.2 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.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.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 Turtle that is nicely formatted and well laid out, but this is not required nor or expected
  • The MIME-type for this format is text/turtle application/fhir+turtle . Other MIME types: application/json-ld for the json-ld variant, and text/shex for the SHEX (RDF schemas)

3.1.1.1 2.6.4.2.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 the identity of the root document - "<>" "<>" in turtle 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 Turtle statements. The focal resource - where to start when parsing - is the resource with the relationship fhir:nodeRole to fhir:treeRoot . if If there is more than one node labeled as a 'treeRoot' in a set of turtle Turtle statements, it cannot be determined how to parse them as a single resource.

3.1.1.2 2.6.4.2.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 (i.e. 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 measn means that the rdf:list structure is not used.

3.1.1.3 2.6.4.2.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

  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 2.6.4.2.4 Representing References

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

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

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

     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.

2.6.4.2.5 Representing Inline Resources

Inline resources - when a resource is contained directly in another element occur in the following places:

Inline resources are represented directly as anonymous nodes. This is an example for a contained Medication resource: 


  fhir:DomainResource.contained [
     a fhir:Medication;
     fhir:index 0;
     # triples for the Medication
  ]

Note that DomainResource.contained has a cardinality of 0..*, so fhir:index is used to order the array.

3.1.1.5 2.6.4.2.6 Representing Concepts

The same logic applies to the Coding data type. These are represented directly in turtle Turtle by serialising serializing 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: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" ]

       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" ("a" in turtle): 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: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" ]

       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, serializer, or injected by a post-processor.

3.1.1.6 2.6.4.2.7 Schema

FHIR uses ShEx for representing the turtle 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 2.6.4.3 RDF Representation of FHIR

In addition to the basic representation of FHIR resources in turtle 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 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 Turtle files: HL7 v3 RIM (Reference Information Model) 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 2.6.4.4 Using RDF with the REST API

TODO

2.6.4.5 Using FHIR/RDF

Application developers wishing to use FHIR/RDF will often need to perform the following rough steps, though exact steps will depend on your application:

  1. Convert FHIR/XML or FHIR/JSON data to/from FHIR/RDF. Open source implementations that can perform this conversion include:
  2. Download the FHIR ontology.
  3. Download other ontologies that you wish to use with your application, such as the SNOMED-CT ontology. (Because of license restrictions, the process of obtaining the SNOMED-CT ontology is more complex than a simple download. Some guidance is provided here .)
  4. Create or obtain a bridge ontology that relates terms in the FHIR ontology to terms in your other ontologies.
  5. Load your FHIR/RDF instance data and your ontologies into a reasoner and/or a triplestore, and perform SPARQL queries and/or reasoning.
  6. If you are creating FHIR/RDF then you might also wish to validate it, using ShEx . If so, you can download the ShEx schema for FHIR/RDF

Slides by Eric Prud'hommeaux illustrate how inference can be used on FHIR/RDF data to perform a query for FHIR Observations of rheumatoid arthritis, using the SNOMED-CT ontology . Caveat: those slides show some terms in the fhir: namespace that do not actually exist in the fhir: namespace, such as fhir:Observation-of-Rheumatoid_arthritis-disorder and fhir:Coding-of-Rheumatoid_arthritis-disorder. A different namespace should have been used in the example.