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.

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.

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").

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

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 (TODO: write said script) can convert lists to OLO-style lists.

Representing Primitive Elements

Primitive elements - elements with a primitive type - are represented as regular (anonymous) nodes so that the element extensions can be represented.  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"^^xsd: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 and double, 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 xsd: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.  @@ TODO 4: Which XSD prefix should we use?  xs: or xsd: ? We should be consistent.  The rest of the FHIR spec seems to use an xs: prefix.  -- YES, CHANGE TO xs: @@

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

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.

Representing Inline Resources

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

• Bundle.entry.resource
• DomainResource.contained
• Parameters.parameter.resource

Inline resources are represented directly 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.

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 "http://hl7.org/fhir/StructureDefinition/observation-bodyPosition"^^xsd:anyURI;  @@ TODO 5: Should this use a bnode and fhir:v?  
If not, how will readers know which FHIR properties have direct scalar values and which use a bnode with fhir:v?   And how would it be extended?
https://build.fhir.org/datatypes.html says "All data types (including primitives) may have extensions".  @@
      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 "http://hl7.org/fhir/StructureDefinition/observation-delta"^^xsd: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:

<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"^^xsd:anyURI ] ;
      fhir:value [ a fhir:boolean ; fhir:v true
    ]
  )
  …

BackboneElements and BackboneTypes are object types. Any RDF predicate which 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"^^xsd:decimal ];
    fhir:unit [ fhir:v "lbs" ];
    fhir:system [
      fhir:v "http://unitsofmeasure.org"^^xsd:anyURI
    ];
    fhir:code [ fhir:v "[lb_av]" ];
    fhir:modifierExtension ([
      fhir:url [ fhir:v "http://example.org/fhir/StructureDefinition/anti-observation"^^xsd:anyURI ] ;
      fhir:value [ a fhir:Code ; fhir:v "draft" ] ;  @@ TODO 8: Verify this example. @@
    ]);
  ]

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 .  If an IRI stem for the Coding.system is published at https://terminology.hl7.org/ it SHOULD be used.  An NPM package is available for automated lookup.

@@ TODO 9: Should we include the Concept IRI algorithm here?  Or reference the google doc proposal? AGREED: Make it an appendix.  @@

RDF Representation of FHIR Definitions