FHIR ShEx Schema

FHIR ShEx [[FHIR-ShEx]] [[Developing-FHIR-ShEx]] is a set of ShEx (Shape Expressions) [[ShExSpec]] schemas designed for validating FHIR RDF data conformance with FHIR StructureDefinition and ElementDefinition conformance rules represented as ShEx shapes. The ShEx schemas for FHIR RDF use "closed-world" semantics, where missing data is assumed to be false and different IRIs are assumed to name different things.

Every publication of the FHIR specification re-builds the FHIR ShEx schema from all core StructureDefinition resources and includes them for download. The most recent build corresponding to the next pre-released version is also available at [[FHIR-ShEx-Build]].

OWL 2 Conformance

The FHIR ontology uses OWL 2 DL (Description Logic) [[owl2-syntax]], which includes subclass axioms defined with owl:allValuesFrom, owl:unionOf, and owl:cardinality.

Because it is intended for use with FHIR Turtle data, the FHIR ontology is currently distributed only in Turtle, while conformant OWL 2 [[owl2-conformance]] tools are only required to support ontologies serialized in RDF/XML. The FHIR ontology may be converted to RDF/XML if needed, but that serialization should not be used with the FHIR XML representation, which does not use RDF.

FHIR primitive type elements include literal data types from XML Schema such as xsd:string, xsd:integer, xsd:anyURI, and xsd:dateTime. OWL 2 does not support xsd:date, xsd:gYear, or xsd:gYearMonth, so values of these types need to be converted to a supported data type such as xsd:dateTime, or to a qualified time:DateTimeDescription, for use with an OWL 2 reasoner.

FHIR R5+ RDF uses RDF collections to track element order, but OWL 2 does not support RDF collections because that vocabulary reserved for the RDF serialization of OWL axioms [[owl2-mapping-to-rdf]]. Applications may translate RDF collections into repeated triples with the fhir:index property used by earlier FHIR RDF versions, either for use with OWL or to enable more concise SPARQL queries. However, conformant FHIR R5+ RDF data is expected to be exchanged and validated using RDF collections.

        :examplePatient a fhir:Patient ;
            fhir:name ( [
                fhir:given ( [ fhir:v "Peter" ] [ fhir:v "James" ] )
            ] [
                fhir:given ( [ fhir:v "Jim" ] )
            ] ) .

        :examplePatient a fhir:Patient ;
            fhir:name [
                fhir:given [ fhir:v "Peter" ; fhir:index 0 ], 
                            [ fhir:v "James" ; fhir:index 1 ] ;
                fhir:index 0 ;
            ] , [
                fhir:given [ fhir:v "Jim" ; fhir:index 0 ] ;
                fhir:index 1 ;
            ] .
        

Mappings

Every FHIR StructureDefinition and ElementDefinition has a mapping to an informal, non-normative taxonomy called W5 ("Five Ws"), which stands for "Who, What, Where, When, Why". The FHIR ontology is distributed with these mappings represented as rdfs:subClassOf relations and with the W5 OWL taxonomy imported, which offers a more intuitive view of how each FHIR resource type is categorized across contexts of use such as clinical, administrative, or financial. These mappings are neither normative nor required and users may remove the owl:imports statement.

FHIR resources may also be mapped to the HL7 RIM (Reference Information Model) [[HL7v3-comparison]], but those mappings are neither required nor represented in the FHIR ontology.

StructureDefinition Classes

A FHIR StructureDefinition defines rules about the structure and content of FHIR resources, elements, and data types. Every FHIR StructureDefinition resource is itself an instance of the StructureDefinition type.

The FHIR ontology maps each StructureDefinition in the core FHIR specification to an OWL class representing the set of instances of that FHIR resource or data type. For example, the class fhir:Patient represents the set of FHIR Patient resources, while fhir:Address represents instances of the FHIR Address data type. Under an RDF interpretation, each OWL class is itself an RDF resource interpreted as a node in a graph. A class extension in RDF is the set of graph nodes interpreted as being instances of that class. An rdf:type triple asserts class membership, but membership may also be inferred from axioms and is not limited to explicitly asserted rdf:type triples.

The FHIR ontology represents the relationship between a StructureDefinition resource instance and its corresponding OWL class with an rdfs:isDefinedBy annotation on the class, so RDF applications can navigate from a FHIR resource to the OWL class it is an instance of, and then to the defining StructureDefinition resource. FHIR ontology classes therefore act as links between FHIR resource or data type instances represented in RDF and their StructureDefinitions. A StructureDefinition resource defines rules about a FHIR resource or data type. Its corresponding FHIR ontology class represents a set of instances of that type. Both are encoded as data in Turtle.

The base definition of a StructureDefinition is another StructureDefinition, which the FHIR ontology maps to an rdfs:subClassOf relation between the corresponding OWL classes. For example, fhir:Patient is a subclass of fhir:DomainResource, which is equivalent to the universal statement: Anything that is a FHIR Patient is also a FHIR DomainResource. If a resource is rdf:type fhir:Patient, then an OWL reasoner should infer that it is also rdf:type fhir:DomainResource.

StructureDefinition.abstract is not represented in the FHIR ontology, but is represented in FHIR ShEx. Explicitly stating that a FHIR resource is an instance of fhir:Base is invalid (non-conformant) because the StructureDefinition for FHIR Base is abstract. This introduces no inconsistency in the FHIR ontology, because every resource is already implicitly rdf:type fhir:Base. But the FHIR ontology does not require this inference to be asserted. Not all invalid data are inconsistent with the FHIR ontology, even though all data inconsistent with the FHIR ontology are invalid.

        # Abbreviated example corresponding to the FHIR StructureDefinition for 'Patient'
        fhir:Patient  rdf:type    owl:Class;
            rdfs:label        "Patient";
            # Provenance annotation and link to StructureDefinition resource instance
            rdfs:isDefinedBy  fhirsd:Patient;
            # StructureDefinition.description
            rdfs:comment      "Demographics and other administrative information about an individual or animal that is the subject of potential, past, current, or future health-related care, services, or processes.";
            # Base definition correspondence and mappings:
            rdfs:subClassOf   fhir:DomainResource, fhirw5:administrative.individual ;
            # ...
            # Example type and cardinality axioms:
            rdfs:subClassOf   [ rdf:type           owl:Restriction ;
                                owl:onProperty     fhir:name ;
                                owl:allValuesFrom  fhir:HumanName
                                ];
            rdfs:subClassOf   [ rdf:type           owl:Restriction ;
                                owl:onProperty     fhir:birthDate ;
                                owl:allValuesFrom  fhir:Date
                                ];
            rdfs:subClassOf   [ rdf:type            owl:Restriction ;
                                owl:onProperty      fhir:birthDate ;
                                owl:maxCardinality  1
                                ];
            # ...
        

ElementDefinition Classes

A FHIR ElementDefinition defines rules about the content of a data element used in a FHIR resource defined in a StructureDefinition. A complex ElementDefinition type, like BackboneElement, defines other ElementDefinitions inside of it. The canonical FHIR ontology maps each complex ElementDefinition to an OWL class whose ElementDefinition.id is mapped to the IRI and rdfs:label. A FHIR "elements ontology" can be produced for all ElementDefinitions, but is not included in the canonical FHIR ontology.

Class IRIs

Each FHIR ontology class is assigned an IRI mapped from the StructureDefinition's name, prefixed with the FHIR namespace <http://hl7.org/fhir/>. The fhir:Patient class has the IRI <http://hl7.org/fhir/Patient>, while the StructureDefinition instance itself is assigned an IRI mapped from its canonical URL, <http://hl7.org/fhir/StructureDefinition/Patient>.

All class IRI paths are named with an uppercase first letter, while all object properties are named with a lowercase first letter. This case-sensitivity avoids punning, where an object property could have the same IRI as a class corresponding to the wrong StructureDefinition. Classes for FHIR primitive types are also named with an uppercase first letter, such as fhir:Code, but are given an rdfs:label annotation with their conventional lowercasing, e.g. “code”.

ElementDefinition Object Properties

Each ElementDefinition within a StructureDefinition is mapped to an OWL object property and assigned an IRI corresponding to the ElementDefinition.id.

Since version R5, FHIR RDF uses short, unqualified object property IRIs corresponding to each ElementDefinition.id, which makes the Turtle serialization easier to read and makes SPARQL queries easier to write. FHIR object properties are fully lowercased, which avoids punning them with a class of the same name: fhir:Code is a class and fhir:code is an object property.

Unqualified object property names result in different ElementDefinitions being mapped to the same object property. Therefore, FHIR R5+ object property names are ambiguous except in the context of their use in FHIR data and OWL class axioms. Each object property instance in a FHIR RDF resource can be disambiguated either from the corresponding ElementDefinition in the StructureDefinition for the resource, or from the corresponding property restriction axioms in the OWL class for the resource. Object properties can also be disambiguated with a SPARQL queries or SWRL (Semantic Web Rule Language) [[SWRL]] rules, which result in punning but only for the correct, corresponding ElementDefinition:

            CONSTRUCT {
                ?p fhir:Patient.name ?n .
            } WHERE {
                ?p a fhir:Patient . 
                ?p fhir:name ?n .
            }
            

            fhir:Patient(?p) ^ fhir:name(?p, ?n) -> fhir:Patient.name(?p, ?n)
            fhir:Account(?a) ^ fhir:name(?a, ?n) -> fhir:Account.name(?a, ?n)
            fhir:Patient.name(?p, ?n) -> fhir:name(?p, ?n)
            fhir:Account.name(?a, ?n) -> fhir:name(?a, ?n)
            

Datatype and Annotation Properties

FHIR RDF represents primitive types -- elements with a single literal value such as a xsd:string -- using the single datatype property fhir:v. The extra fhir:v prevents cases where a choice type could either be a primitive type or a non-primitive type. Primitive types, like all FHIR data types, are extensible, and so the fhir:v assertion allows elements to add a FHIR Extension such as Data Absent Reason.

No FHIR-specific annotation properties are currently defined. StructureDefinition.description and ElementDefinition.definition map to rdfs:comment, and rdfs:isDefinedBy links each derived OWL class or object property to its corresponding StructureDefinition or ElementDefinition.

Element Types

An ElementDefinition may define a target element type, the value of which is defined by a StructureDefinition, and therefore represented by an OWL class. For example, Observation.effective may have the ElementDefinition.type dateTime, represented by the class fhir:DateTime.

A FHIR dateTime is defined as a union of the XML Schema types xsd:dateTime, xsd:date, xsd:gYearMonth, and xsd:gYear. Because the literal value of a primitive type element is represented with fhir:v, fhir:DateTime has an axiom stating that all of its fhir:v values are members of the owl:unionOf those types.

FHIR choice types, or polymorphic types, are also represented with owl:unionOf. For example, Observation.effective can be a dateTime, instant, Period, or Timing, so fhir:Observation is a subclass of the things whose fhir:effective values are only instances of fhir:DateTime, fhir:Instant, fhir:Period, or fhir:Timing. In FHIR RDF, an instance of a choice type includes an rdf:type assertion stating which of these types it is. This is analogous to the type being suffixed to the element name in JSON, as in the "effectiveDateTime" property of an FHIR JSON Observation.

Reference Types

A FHIR reference type constrains an element to refer, by string value, to a FHIR resource of some specified type. For example, every Condition.subject must refer to a resource of type Patient or Group. FHIR RDF makes references easier to resolve by asserting an additional Resource Link to an IRI for the referenced resource. The FHIR ontology represents the target types with an owl:allValuesFrom axiom on fhir:l.

Element Cardinality

The cardinality of an ElementDefinition defines how many values the element may have. In the FHIR ontology, element cardinality is mapped to owl:cardinality, owl:minCardinality, and owl:maxCardinality axioms on the class corresponding to its StructureDefinition. For example, Observation.status has a minimum and maximum cardinality of 1, so fhir:Observation is a subclass of resources related via fhir:status to exactly 1 instance. Cardinality axioms are separate from reference type axioms.

Minimum cardinality axioms in OWL are not generally inferred to be inconsistent with any particular RDF data, due to its open-world semantics. An instance of fhir:Observation may be missing a fhir:status, but an OWL reasoner will not assume that the missing data does not exist anywhere. For validation purposes, the FHIR ShEx schema should instead be used to check whether the required data is present. Minimum cardinality axioms are more useful as sufficient conditions in owl:equivalentClass axioms for .

Maximum cardinality axioms are more useful for detecting inconsistencies, but they can also lead to unintuitive inferences. For example, Observation.encounter has at most 1 Encounter. If a fhir:Observation is related to two instances of fhir:Encounter, which is invalid/non-conformant, an OWL reasoner will infer that they are the same unless given a reason why they are distinct, such as an owl:differentFrom assertion. Fortunately, FHIR data almost always distinguishes such elements by their : since all FHIR primitive type classes have an exact cardinality of 1 fhir:v, two elements with different fhir:v literals cannot be inferred to be the same.

Element Slicing

A FHIR slicing type may have multiple values of different element types and with different cardinality constraints. The FHIR ontology maps these elements to owl:qualifiedCardinality axioms.

FHIRPath Constraints

FHIRPath [[FHIRPath]] expressions are not mapped to OWL axioms, but may be in the future.

ValueSet Bindings

ValueSet bindings are represented by incomplete element type axioms; they do not specify which codes the bound ValueSet contains. Complete OWL representations of ValueSet bindings may be added in the future.

Analytics

Custom, defined classes can encode reuseable logic that composes with SPARQL queries [[Blending-FHIR-OWL]]. This works especially well with Concept IRIs for external OWL classes corresponding to terminology codes. For example, here is a complex FHIR SPARQL query for all Patients with some DiagnosticReport with the SNOMED code for "Malignant neoplastic disease", 363346000.

SELECT ?patient WHERE {
    ?diagnosticReport a fhir:DiagnosticReport ;
        fhir:conclusionCode [
            fhir:concept [
                fhir:coding/rdf:rest*/rdf:first [
                    fhir:code [ fhir:v "363346000" ] ;
                    fhir:system [ fhir:v "http://snomed.info/sct"^^xsd:anyURI ]
                ]
            ]
        ] ;
        fhir:subject/fhir:l ?patient .

    ?patient a fhir:Patient .
}
            

This logic can be re-defined in an OWL class that also takes advantage of FHIR RDF concept IRIs:

# "DiagnosticReport and conclusionCode only (concept only 'Malignant neoplastic disease (disorder)')"
:CancerReport a owl:Class ;
    owl:equivalentClass [ 
        owl:intersectionOf ( 
            fhir:DiagnosticReport
            [ rdf:type owl:Restriction ;
              owl:onProperty fhir:conclusionCode ;
              owl:someValuesFrom [ 
                    rdf:type owl:Restriction ;
                    owl:onProperty fhir:concept ;
                    owl:someValuesFrom sct:363346000
              ]
            ]
        )
    ] .

This OWL class provides two benefits: First, it can classify not only DiagnosticReports coded with 363346000, but also DiagnosticReports with any code subsumed by 363346000. Second, the class can be reused to compose multiple different queries, or other classes, in a consistent way.

SELECT ?patient WHERE {
    ?diagnosticReport a :CancerReport ;
        fhir:subject/fhir:l ?patient .

    ?patient a fhir:Patient .
}
            

An example of further composition:

# "Patient and ( inverse (l) some ( inverse (subject) some CancerReport))"
:PatientWithCancerReport rdf:type owl:Class ;
    owl:equivalentClass [ 
        owl:intersectionOf ( 
            fhir:Patient
            [ rdf:type owl:Restriction ;
              owl:onProperty [ owl:inverseOf fhir:l ] ;
              owl:someValuesFrom [ rdf:type owl:Restriction ;
                                   owl:onProperty [ owl:inverseOf fhir:subject ] ;
                                   owl:someValuesFrom :CancerReport
                                 ]
            ]
        )
] .

Enabling SPARQL queries to be further reduced to:

SELECT ?patient WHERE {
    ?patient a :PatientWithCancerReport .
}
            

Ontology-Based Data Access systems such as Ontop [[FHIR-Ontop-OMOP]] can rewrite OWL QL [[owl2-profiles]] axioms and SPARQL queries to SQL, especially to enable data transformation.

Simplified "knowledge graphs" may also be derived from the FHIR ontology for the purpose of more compactly representing queryable FHIR resource and element relationships.

Finally, terminology mappings using rdfs:subClassOf, owl:equivalentClass, or SKOS [[skos-reference]] may be used instead of FHIR ConceptMap resources.