Release 5 Ballot

This page is part of the FHIR Specification (v5.0.0-ballot: R5 Ballot - see ballot notes). 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

2.1.6.6 Resource Description Framework (RDF) Representation

Implementable Technology Specifications icon Work GroupMaturity Level: 3Standards Status: Trial Use
W3C RDF icon

This page and the RDF forms are jointly maintained by the HL7 FHIR project -- especially the RDF subgroup icon of the ITS work group icon -- and the W3C Semantic Web Health Care and Life Sciences Interest Group icon.

FHIR resources can be represented as an RDF graph icon serialized in the Turtle format icon. 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 from the JSON and XML representations, and would be used for different reasons. Systems focused on operational exchange of data would not generally choose to use RDF.

This page describes:

2.1.6.6.1 Turtle Template for Resources

Each resource page has a set of language templates describing the FHIR expression in that language. The Turtle representation for a resource is described using this format: 

[ a fhir:Observation; 
  fhir:nodeRole fhir:treeRoot; # if this is the parser root
  # from Resource: id; meta; implicitRules; and language
  # from DomainResource: text; contained; extension; and modifierExtension
  fhir:Observation.identifier [ Identifier ]; # 0..* Unique Id for this particular observation
  fhir:Observation.status [ fhir:v "<code>" ]; # R!  registered | preliminary | final | amended +
  fhir:Observation.code [ CodeableConcept ]; # 1..1 R!  Type of observation (code / type)
  fhir:Observation.subject [ fhir:reference [ Patient|Group|Device|Location ... ] ]; # 0..1 Who and/or what this is about
  fhir:Observation.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 4:
    fhir:Observation.effectiveDateTime [ fhir:v "<dateTime>" ];
    fhir:Observation.effectivePeriod [ Period ];
    fhir:Observation.effectiveTiming [ Timing ];
    fhir:Observation.effectiveInstant [ fhir:v "<instant>" ];
]

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.
  • 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 or expected.

2.1.6.6.2 FHIR RDF Example

An example FHIR RDF Observation illustrates the Turtle language and the additional conventions used by FHIR RDF: 

PREFIX fhir: <http://hl7.org/fhir/>
PREFIX xs: <http://www.w3.org/2001/XMLSchema#>
PREFIX owl: <http://www.w3.org/2002/07/owl#>

                                  # Obs123 (subject) hasType (predicate) fhir:Observation
<http://hl7.org/fhir/Observation/Obs123> a fhir:Observation;
  fhir:nodeRole fhir:treeRoot;    # (subject) is the serialization root of this document
  fhir:status [ fhir:v "final" ]; # (subject) has an (extensible) status of "final"
  fhir:code [                     # (subject) as a code
    fhir:coding (                 #  which has codings
      [                           #   with a system, code and concept identifier
        a <http://loinc.org/rdf#29463-7> ;
        fhir:system [
          fhir:v "http://loinc.org"^^xs:anyURI
        ];
        fhir:code [ fhir:v "29463-7" ]
      ]
      [                           #  and another with a display
        a <http://loinc.org/rdf#3141-9> ;
        fhir:system [
          fhir:v "http://loinc.org"^^xs:anyURI
        ];
        fhir:code [ fhir:v "3141-9" ];
        fhir:display [ fhir:v "Body weight Measured" ]
      ]
    )
  ];
  fhir:value [                    # the value is an anonymous node
    a fhir:Quantity;              #   which has a type (Quantity), and 21090 parts.
    fhir:value [ fhir:v "185"^^xs:decimal ];
    fhir:unit [ fhir:v "lbs" ];
    fhir:system [
      fhir:v "http://unitsofmeasure.org"^^xs:anyURI
    ];
    fhir:code [ fhir:v "[lb_av]" ]
  ].

                                  # Metadata about OWL interpretation
<http://hl7.org/fhir/Observation/Obs123.ttl> a owl:Ontology;
  owl:imports fhir:fhir.ttl;
  owl:versionIRI <http://hl7.org/fhir/Observation/Obs123.ttl>.

In this example,

  • the subject IRI is wrapped with '< ... >'.
  • the type (fhir:Observation) and following predicates (e.g. fhir:status) are prefixed names (like XML namespaced names),
  • assertions following a ';' re-use the same subject,
  • anonymous nodes are declared with '[ ... ]'s,
  • and literals with a quoted value and an optional datatype preceded by '^^' (e.g. "final").

2.1.6.6.3 FHIR RDF Serialization Conventions

FHIR RDF imposes additional conventions to simplify recognition and manipulation of FHIR RDF graphs.  Although RDF graphs in general may be serialized in various RDF formats, FHIR RDF mandates support specifically for Turtle icon. All FHIR RDF documentation is expressed in Turtle.   And while the standard media type for Turtle is text/turtle, the use of Turtle for FHIR RDF uses the specialized media type application/fhir+turtle.

FHIR uses Shape Expressions (ShEx) icon to define and validate FHIR RDF. See fhir.shex for the complete FHIR RDF schema. Each Resource page includes a link for the subset of fhir.shex needed to describe that Resource. The media type for ShEx is text/shex.

2.1.6.6.3.1 Representing Resources

Each resource is represented as a set of RDF triples. 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. In the above example, the resource is the subject: <http://hl7.org/fhir/Observation/Obs123>.

Some resources can contain other resources. Given that the relationships can appear in any order in RDF, 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 labeled as a 'treeRoot' in a set of Turtle statements, it cannot be determined how to parse them as a single resource.

2.1.6.6.3.2 Case Sensitivity

While RDF predicate names are case-sensitive, FHIR avoids confusion by assuring that there are no predicates that differ only in case. For example, there will be no fhir:Code predicate because there is already a fhir:code predicate.

2.1.6.6.3.3 Nested Anonymous Nodes

Content within a resource is always represented with anonymous nodes (a/k/a "blank nodes").  Only FHIR Resource nodes can be IRIs. For example, < ... /Obs123> fhir:status [ fhir:v "final" ] asserts that:

  • < ... /Obs123> has a status of some anonymous node.
  • That anonymous node has a fhir:v of "final" (the literal "final").

2.1.6.6.3.4 Property Names

A great deal of effort has gone into unifying FHIR property names across resources and datatypes. These defined properties effectively declare the FHIR RDF namespace with a set of polymorphic, reuseable predicates. For example, fhir:status is spelled the same way regardless of whether it appears in an Observation, Diagnosis, or any other FHIR Resource.

In other formats (XML, JSON), FHIR properties with choice datatypes, like value[x], are appended with the datatype, e.g. valueQuantity. In RDF, this is written fhir:value and the object asserts its type, as in the above example:

  fhir:value [ a fhir:Quantity; ... ]

2.1.6.6.3.5 Representing Repeating Elements

Elements that can repeat are represented with RDF lists (officially called "RDF collections") in order to retain the order of their elements. 

    ( elt1 elt2 ... )

which produces an RDF list structure the the elements elt1 and elt2. In the above example, the fhir:code has a fhir:coding with two members: 

    fhir:coding (
      [ a <http://loinc.org/rdf#29463-7> ... ]
      [ a <http://loinc.org/rdf#3141-9> ... ]
    )

A script icon can convert RDF lists to OLO-style lists icon, which may be helpful for OWL users. See Using FHIR RDF with OWL for more info.

2.1.6.6.3.6 Representing Primitive Elements

Primitive elements - elements with a primitive type - are represented as anonymous nodes so that the element extensions can be attached.  The actual value of the primitive type is represented as an RDF Literal using the fhir:v predicate.  fhir:v is the only FHIR property that directly holds an RDF literal, and it always holds an RDF Literal: 

  fhir:v "[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

In the above example, the Quantity has a fhir:value which is an anonymous node with a fhir:v in it: 

    [ fhir:v "185"^^xs:decimal ]

Note that the correct XSD type for a FHIR decimal, date, or dateTime must be determined by inspecting the value of the date for conformance with one of the union types for that type. In the case of FHIR decimal, which is a union of XSD decimal icon and double icon, any value with an 'e' or 'E' in it is a double, otherwise it is a decimal. For example, the lexical value "185" is given the datatype xs:decimal.

The fhir:v 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. 

2.1.6.6.3.7 Representing References

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

  fhir:Observation.subjectReference [
     fhir:Reference.reference [ fhir:v "Patient/example" ];
     fhir:Reference.display [ fhir:v "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 (optional) fhir:link property: 

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

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.1.6.6.3.8 Representing Inline Resources

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

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

  fhir:DomainResource.contained ([
     a fhir:Medication;
     # triples for the Medication
  ])

Note that DomainResource.contained has a cardinality of 0..*, so an RDF List is used to order the array.

2.1.6.6.3.9 Representing Concepts

The same logic applies to the Coding data type. These are represented directly in Turtle by serializing their properties as specified above: 

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

For reasoners using the RDF graph, it's very useful to make the implicit concept references in these Codings explicit, by specifying a concept IRI in an (optional) rdf:type assertion, written as a in Turtle: 

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

A concept IRI typically has two parts: an IRI stem and a code.  An IRI stem is the initial substring, of an IRI, that is used to create concept IRIs for codes in a particular vocabulary.  The IRI stem normally corresponds directly to an IRI prefix in Turtle, such as loinc: or sct: in the above example.  The concept IRI for a given <Coding.system, Coding.code> pair is typically formed by: 1. looking up the appropriate IRI stem corresponding to the Coding.system; 2. concatenating the IRI stem with the percent encoded Coding.code .  Some vocabularies may also define Coding.codes that are already concept IRIs, bypassing the need for the IRI stem.  For details see Appendix: Algorithm for creating a Concept IRI.

If an IRI stem for the Coding.system is published at https://terminology.hl7.org/ icon it SHOULD be used.   An NPM package is available icon to efficiently automate lookup of IRI stems from Coding.systems.

2.1.6.6.3.10 Modifier Extensions

A Resource may have any number of non-modifier extensions: 

<http://hl7.org/fhir/MedicationRequest/MR321> a fhir:Observation;
  fhir:nodeRole fhir:treeRoot;
  fhir:extension (
    [ fhir:url [ fhir:v "http://hl7.org/fhir/StructureDefinition/observation-bodyPosition"^^xs:anyURI ] ;
      fhir:value [
        fhir:coding (
          a sct:33586001;
          fhir:system [ fhir:v "http://snomed.info/sct" ];
          fhir:code [ fhir:v "33586001" ];
          fhir:display [ fhir:v "Sitting position (finding)" ]
        ) ] ]
    [ fhir:url [ fhir:v "http://hl7.org/fhir/StructureDefinition/observation-delta"^^xs:anyURI ] ;
      fhir:value [
        fhir:coding (
          a sct:1250004;
          fhir:system [ fhir:v "http://snomed.info/sct" ];
          fhir:code [ fhir:v "1250004" ];
          fhir:display [ fhir:v "Decreased (qualifier value)" ]
        ) ] ]
  )
  ...

FHIR allows modifierExtensions on DomainResources, BackboneElements and BackboneTypes. The type of any DomainResource with any modifierExtension is prefixed with '_' in RDF. The '_' prefix helps prevent FHIR RDF processors that do not understand a particular modifier extension from blindly processing it as though it still had the original semantics.  The structure of the element is otherwise unchanged:

<http://hl7.org/fhir/MedicationRequest/MR321> a fhir:_MedicationRequest;
  fhir:nodeRole fhir:treeRoot;
  fhir:extension ( ... );           # above bodyPosition and delta extensions
  fhir:modifierExtension (
    [
      fhir:url [ fhir:v "http://example.org/fhir/StructureDefinition/anti-prescription"^^xs:anyURI ] ;
      fhir:value [ a fhir:boolean ; fhir:v true ]
    ]
  )
  ...

BackboneElements and BackboneTypes are object types. Any RDF predicate that references a modified BackboneElement or BackboneType is prefixed with a '_'. 

<http://hl7.org/fhir/Observation/Obs123> a fhir:Observation;
  ...
  fhir:_value [
    a fhir:Quantity;
    fhir:value [ fhir:v "185"^^xs:decimal ];
    fhir:unit [ fhir:v "lbs" ];
    fhir:system [
      fhir:v "http://unitsofmeasure.org"^^xs:anyURI
    ];
    fhir:code [ fhir:v "[lb_av]" ];
    fhir:modifierExtension (
      [
        fhir:url [ fhir:v "http://example.org/fhir/StructureDefinition/anti-observation"^^xs:anyURI ] ;
        fhir:value [ a fhir:boolean ; fhir:v true ]
      ]
    ) ;
  ]

2.1.6.6.4 RDF Representation of FHIR Definitions

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: HL7 v3 RIM (Reference Information Model) and FHIR.  ShEx schemas that describe FHIR's RDF format are also available.

2.1.6.6.5 Relationship Between RDF, FHIR, and Ontologies

Informative

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 other RDF data and 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 FHIR's RDF format and other uses of ontologies.

FHIR's 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 on this page fhir:nodeRole, fhir:treeRoot, fhir:v and fhir:concept.

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.

2.1.6.6.6 Usage Guidance

Informative

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 icon. )
  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 icon. If so, you can download the ShEx schema for FHIR RDF

2.1.6.6.6.1 Using FHIR RDF with OWL

RDF lists use a ladder of rdf:first and rdf:rest properties. This can cause problems in OWL DL, which disallows axioms over the rdf: namespace. To work around this problem, OWL users can convert RDF lists in their FHIR data to use OLO-style icon lists. A script icon is available for doing the conversion.

2.1.6.6.6.2 Tutorials

Slides by Eric Prud'hommeaux icon 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 icon.

A webinar by Harold Solbrig icon shows how FHIR RDF data can be used with the SNOMED-CT ontology icon to recognize a cancer diagnosis.  An associated tutorial icon details the steps used.  Caveat: this webinar and tutorial used a previous version of FHIR RDF.

2.1.6.6.7 Appendix: Algorithm for Creating a Concept IRI

This section defines a standard algorithm for generating a Concept IRI from a <Coding.system, Coding.code> pair.  In many cases it involves merely concatenating the associated IRI Stem with the Coding.code.  But because a Coding.code could contain reserved characters that are used to delineate different parts of the IRI, percent-encoding of reserved characters is required, as defined below.

Given:

  • a FHIR Coding.system, s, that identifies a terminology t; and
  • a Coding.code, c, that is defined within t;

a Concept IRI, conceptIRI, corresponding to s and c is computed as follows:

  1. If no IRI Stem is defined for s in the HL7 Terminology website icon, then conceptIRI is undefined. Halt.
  2. Let iStem be an IRI Stem that is defined for s in the HL7 Terminology website. 
  3. As a special case, if iStem equals urn:ietf:rfc:3987, then conceptIRI is c, and c MUST be a syntactically valid absolute-IRI as defined by RFC 3987 icon.  Halt.  (Informative comments: The purpose of this special case is to permit System.codes that are already IRIs to be used directly as Concept IRIs, without any transformation. Note that an absolute-IRI may also be a URL or a URN.)
  4. Let cSafe be the IRI-safe version of c, as defined by the algorithm in section 7.3 of R2RML: RDB to RDF Mapping Language (W3C Recommendation 27 September 2012) icon, quoted here for convenience (informative):
    The IRI-safe version of a string is obtained by applying the following transformation to any character that is not in the iunreserved production icon in [RFC3987]:
    1. Convert the character to a sequence of one or more octets using UTF-8 [RFC3629]
     2. Percent-encode icon each octet [RFC3986]
    The iunreserved production defined in RFC 3987, section 2.2 icon using ABNF icon is also quoted here for convenience (informative):
    iunreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~" / ucschar
    The ucschar production defined in RFC 3987, section 2.2 icon is also quoted here for convenience (informative).  (Informative comment: The ucschar production defines international character ranges that are valid unicode characters within the intersection of path components (ipath), query strings (iquery) and fragment identifiers (ifragment).  They do not include any reserved characters involved in parsing apart the various components of an IRI.)
    ucschar        = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF
                       / %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD
                       / %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD
                       / %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD
                       / %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD
                       / %xD0000-DFFFD / %xE1000-EFFFD
  5. conceptIRI is the result of concatenating iStem and cSafe. Halt.

Some real and hypothetical examples are shown in the following table.

Coding.system

Coding.code

IRI Stem

Concept IRI

ICD 10:
http://hl7.org/fhir/sid/icd-10

G44.1

http://purl.bioontology.org/ontology/ICD10/

http://purl.bioontology.org/ontology/ICD10/G44.1 

SNOMED CT:*
http://snomed.info/sct

128045006

http://snomed.info/id/

http://snomed.info/id/128045006

MeSH: https://www.nlm.nih.gov/mesh

D000305

https://id.nlm.nih.gov/mesh/

https://id.nlm.nih.gov/mesh/D000305

LOINC: http://loinc.org

35217-9

https://loinc.org/rdf/

https://loinc.org/rdf/35217-9

Example coding system that uses a Unicode smiling face character (U+263A) as a code:
http://example.org/

☺

http://example.org/

http://example.org/☺

Example coding system that uses a Unicode waving hand character (U+1F44B) from the Miscellaneous Symbols and Pictographs icon block icon, combined with the medium-dark skin tone (U+1F3FE):
http://example.org/

👋🏾

http://example.org/

http://example.org/👋🏾 

*As of this writing (5-Sep-2022) it is not clear what IRI stem should be used when writing a post-coordinated code expression.