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. ShEx schemas 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 schemas from all core StructureDefinition resources and includes them for download. The most recent build corresponding to the next pre-release version is also available at [[FHIR-ShEx-Build]].

OWL 2 Conformance

The FHIR ontology uses OWL 2 DL (Description Logic) [[owl2-syntax]] vocabulary, which includes subclass axioms defined with owl:allValuesFrom, owl:unionOf, and owl:cardinality. The ontology is not entirely conformant with OWL 2 due it its inclusion of a few data types described below.

FHIR primitive type elements include literal data types from XML Schema [[xmlschema11-2]] such as xsd:string, xsd:integer, xsd:anyURI, and xsd:dateTime. OWL 2 does not support xsd:date, xsd:time, 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 generally support RDF collections because that vocabulary is reserved for the RDF serialization of OWL axioms [[owl2-mapping-to-rdf]]. Applications could translate RDF collections into indexed 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.

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 could be converted to RDF/XML if needed, but that serialization is not intended to be used with the FHIR XML representation, which does not use RDF.

        :patient1 a fhir:Patient ;
            # RDF collections
            fhir:name ( [
                fhir:given ( [ fhir:v "Peter" ] [ fhir:v "James" ] )
            ] [
                fhir:given ( [ fhir:v "Jim" ] )
            ] ) .

        :patient2 a fhir:Patient ;
            # Indexed triples
            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 defined for a FHIR resource 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 and rdfs:subPropertyOf 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, so removing the owl:imports statement and corresponding mappings will not affect the FHIR ontology.

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.

Structure Definitions

A FHIR structure definition or 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 [[FHIR]], except for example FHIR profiles, to an OWL class representing the set of valid instances of that FHIR resource or data type. For example, the class fhir:Patient represents the set of valid FHIR Patient resources, while fhir:Address represents the set of valid FHIR Address typed data elements.

Each 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.

An OWL class interpreted as an RDF class is just another RDF resource. A class extension is the set of resources that are 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 RDF resource or data type instances and their StructureDefinitions.

To summarize: A StructureDefinition resource defines rules about a FHIR resource or data type. Its corresponding FHIR ontology class represents a set of valid instances of that type. Both are encoded as data in Turtle.

        # Abbreviated example corresponding to the FHIR StructureDefinition for 'Patient'
        fhir:Patient a 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." ;
            # StructureDefinition.baseDefinition 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
                              ] ;
            rdfs:subClassOf   [ rdf:type           owl:Restriction ;
                                owl:allValuesFrom  fhir:Patient.contact ;
                                owl:onProperty     fhir:contact
                              ] ;
            # ...
        

Element Definitions

A FHIR element definition or ElementDefinition defines rules about the content of a data element used in a FHIR resource defined in a StructureDefinition. A complex element like Patient.contact has child elements, each defined by its own ElementDefinition. The canonical FHIR ontology maps each complex ElementDefinition to a separate OWL class to avoid complex nesting of axioms in the corresponding StructureDefinition class. Most of these are subclasses of fhir:BackboneElement but some are subclasses of fhir:Element. Complex elements in FHIR RDF do not include type assertions for these classes. They are simply used to organize the ontology and have no effect on FHIR data generally. A FHIR "elements ontology" can be derived for all ElementDefinitions, but is not included in the canonical FHIR ontology.

Classes derived from ElementDefinitions are indicated by an rdfs:isDefinedBy annotation to a fragment of a StructureDefinition, e.g. http://hl7.org/fhir/StructureDefinition/Patient#Patient.contact shown in Example 5.

# Abbreviated example corresponding to the FHIR ElementDefinition for 'Patient.contact'
fhir:Patient.contact  a  owl:Class ;
    rdfs:label        "Patient.contact" ;
    # Provenance annotation and link to ElementDefinition element instance
    rdfs:isDefinedBy  <http://hl7.org/fhir/StructureDefinition/Patient#Patient.contact> ;
    # ElementDefinition.definition
    rdfs:comment      "A contact party (e.g. guardian, partner, friend) for the patient." ;
    # ElementDefinition.type.code
    rdfs:subClassOf   fhir:BackboneElement ;

    # ...

    # 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:name ;
                        owl:maxCardinality  1
                      ] ;
    rdfs:subClassOf   [ rdf:type           owl:Restriction ;
                        owl:onProperty     fhir:telecom ;
                        owl:allValuesFrom  fhir:ContactPoint 
                      ] ;
    rdfs:subClassOf   [ rdf:type           owl:Restriction ;
                        owl:onProperty     fhir:address ;
                        owl:allValuesFrom  fhir:Address 
                      ] ;
    # ...
        

Class IRIs

All class IRI local names are named with an uppercase first letter (e.g. http://hl7.org/fhir/Patient or fhir:Patient), 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".

Object Properties

Each ElementDefinition within a StructureDefinition is mapped to an OWL object property and assigned an IRI corresponding to the last segment of the ElementDefinition.path. The object property fhir:l is used only in FHIR RDF for resource links. The object property fhir:nodeRole is used only in FHIR RDF and only when serializing contained FHIR resources as separate RDF resources in a single document. For example, fhir:nodeRole fhir:treeRoot identifies the top-level, containing FHIR resource.

Since version R5, FHIR RDF uses short, unqualified object property IRIs corresponding to each ElementDefinition.path, which makes the Turtle serialization easier to read and makes SPARQL queries easier to write. FHIR object properties have lowercased first letters, which avoids punning them with a class of the same name. For example, 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. FHIR R5+ object property names are therefore 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 SPARQL queries (Example 6) or SWRL (Semantic Web Rule Language) [[SWRL]] rules (Example 7), which could result in punning, but only for a class corresponding to the correct 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)
            

Data and Annotation Properties

FHIR RDF represents primitive types — elements with a single literal value such as an xsd:string — using the single data property fhir:v. Primitive types, like all FHIR data types, are extensible, and so the fhir:v assertion allows a primitive type element to add a FHIR Extension. The extra fhir:v also prevents punning some choice type elements that can either be a primitive type or non-primitive type (e.g. Observation.value) as both an data property and object property, which would be non-conformant with OWL 2.

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(s).

Base Definitions

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 will infer that it is also rdf:type fhir:DomainResource.

StructureDefinition.abstract means that resources defined by this type shall not be instantiated without instantiating a more specific, non-abstract type. For example, a FHIR resource is invalid if it is asserted to be an instance of fhir:Resource and not a more specific class corresponding to a non-abstract StructureDefinition. The FHIR ontology does not represent StructureDefinition.abstract with an axiom because, in this example, every resource is already implicitly rdf:type fhir:Resource. But OWL does not require this inference to be asserted due to its open-world semantics.

Element Types

An ElementDefinition may define a target element type, the value of which is defined by a StructureDefinition, and therefore represented as an OWL class. For example, if a valid Patient.active element has a value, then its type is boolean, represented as the class fhir:Boolean. The FHIR ontology represents target type relations with owl:allValuesFrom axioms.

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 owl:unionOf axiom stating that all of its fhir:v values are one of those XML Schema 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 a FHIR JSON Observation.

Reference Types

The reference type of an ElementDefinition defines the type of FHIR resource the element refers to, if at all. For example, every valid Condition.subject refers only to a resource of type Patient or Group. Each FHIR RDF fhir:Reference element optionally asserts an additional fhir:l (resource link) to an IRI for the referenced resource. The FHIR ontology represents reference type relations with owl:allValuesFrom axioms on fhir:l.

Element Cardinality

The cardinality of an ElementDefinition defines how many values the element could have. The FHIR ontology represents element cardinality with owl:cardinality, owl:minCardinality, and owl:maxCardinality axioms on the class corresponding to its StructureDefinition or parent, complex ElementDefinition. For example, Condition.subject has a minimum and maximum cardinality of 1, so every valid fhir:Condition instance is related via fhir:subject to exactly one thing. Cardinality axioms are separate from reference type axioms.

Minimum cardinality axioms in OWL are usually not inconsistent with RDF data due to its open-world semantics. An instance of fhir:Condition may be missing a fhir:subject, but an OWL reasoner will not assume that the missing data does not exist anywhere, or that the represented condition is not associated with anyone. A closure axiom stating that the fhir:Condition resource only has the fhir:subject values explicitly stated would be needed for an inconsistency. For validation purposes, the FHIR ShEx schema can 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 analytics.

Maximum cardinality axioms can detect some inconsistencies for invalid data, but they can also lead to unintuitive inferences. If a fhir:Condition has more than one fhir:subject (which would be invalid in a closed-world interpretation), an OWL reasoner would infer that the subjects are the same, unless given a reason why they are distinct. Fortunately, FHIR resources and elements can be distinguished by their primitive type elements. Two instances of fhir:Patient with different fhir:id values will be inferred to be distinct, because fhir:Id has at most one fhir:v literal value. Similarly, any other primitive type elements like fhir:String or fhir:Uri are uniquely identifiable by their required fhir:v values, and therefore necessarily distinct.

Element Slicing

A FHIR sliced element type could have multiple values of different element types and with different cardinalities. Slicing types are only used in FHIR profiles, not in the core, normative FHIR StructureDefinitions, and therefore are not represented in the FHIR ontology. Profiles may be similarly mapped to OWL classes and slicing types represented with owl:qualifiedCardinality axioms.

FHIRPath Constraints

FHIRPath expressions are not mapped to OWL axioms but could be in the future.

ValueSet Bindings

The ValueSet bindings of an ElementDefinition specifies which sets of codes are intended be used as values for this element. The FHIR ontology does not represent ValueSet bindings but could in the future.

Analytics

Custom, defined classes can encode reusable logic that composes with SPARQL queries [[Blending-FHIR-OWL]]. This works especially well with concept IRIs for external OWL classes corresponding to terminology codes. Example 8 is a FHIR SPARQL query for all Patients with some DiagnosticReport with the SNOMED code for "Malignant neoplastic disease", 363346000. This simplified query assumes the data includes no RDF collections.

SELECT ?patient WHERE {
    ?diagnosticReport a fhir:DiagnosticReport ;
        fhir:conclusionCode [
            fhir:concept [
                fhir:coding [
                    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 in Example 9 that takes advantage of FHIR RDF concept IRIs instead of relying on literal code values. The owl:someValuesFrom axiom is equivalent to owl:minCardinality 1 owl:Thing.

# "fhir:DiagnosticReport 
#  and fhir:conclusionCode some 
#     (fhir:concept some '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
              ]
            ]
        )
    ] .

Given a relevant fragment of SNOMED OWL (at least the term sct:363346000 and its subclasses) [[SNOMED-OWL-Toolkit]], an OWL 2 EL [[owl2-profiles]] reasoner like ELK [[ELK]] will infer the statement a :CancerReport on any matching data. These inferred statements can be saved to a materialized graph, similar to a materialized view.

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

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

    ?patient a fhir:Patient .
}
            

Example 11 shows further composition using terms like owl:inverseOf, which goes beyond OWL 2 EL.

# "fhir:Patient 
#  and ( inverse (fhir:l) some 
#      ( inverse (fhir: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
                                 ]
            ]
        )
] .

Materializing the inferred instances of this class enables SPARQL queries to be further reduced to Example 12:

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

In other contexts, simplified "knowledge graphs" may also be derived from the FHIR ontology, using SPARQL queries, for the purpose of more compactly representing queryable FHIR resource type and element type relationships. For example, one might derive a triple like fhir:Patient fhir:contact fhir:Patient.contact. Note that this is not conformant OWL 2, which distinguishes between classes and individuals.

Mapping

The FHIR ontology can be used to map between FHIR and non-FHIR concepts or data using techniques that do not rely on FHIR-specific tooling, for example in .

Ontology-based data access systems such as Ontop (open-source) can rewrite OWL 2 QL [[owl2-profiles]] axioms and SPARQL queries to SQL. This has been used with the FHIR ontology to dynamically rewrite FHIR SPARQL [[FHIR-Ontop-OMOP]] to SQL queries on OMOP relational data [[OMOP]].

Terminology mappings using rdfs:subClassOf, owl:equivalentClass, or SKOS [[skos-reference]] can sometimes be used instead of FHIR ConceptMap resources. This enables FHIR data to be queried with both terminology expansion and mapping transformations implemented as logical inference.

Finally, FHIR resources could be interpreted more literally as information models to better integrate with some scientific ontologies, like those from the Open Biological and Biomedical Ontology Foundry [[OBO]]. For example, the relationship between a coded data element and a concept IRI could be interpreted with a mapping from the Information Artifact Ontology. Example 13 shows an Observation.code element that is about (obo:IAO_0000136) a clinical finding of tinnitus, interpreted to be something that someone participates in (to say the least) [[SNOMED-BFO-Schulz]]. The tinnitus itself is represented as a phenotypic abnormality in the context of the Human Phenotype Ontology, but its direct relationship to the clinical finding is left unspecified. The person who has the tinnitus is represented by both a fhir:Patient and a fhir:Person resource to show that these are distinct in FHIR.

Many alternative interpretations are possible. Tinnitus can be modeled as associated with a kind of symptom, disease, disorder, process, disposition, etc. depending on the context. A mapping is valuable not only when it is correct, but also when it helps us understand exactly why it might be incorrect. Note that the FHIR RDF data in Example 13 is not conformant for exchange and the core FHIR specification does not endorse any mappings like these, which will vary depending on the data, codes, and ontologies involved.

@prefix obo:  <http://purl.obolibrary.org/obo/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

:exampleObservationRecord a fhir:Observation ;
    fhir:subject [
        fhir:reference [ fhir:v "Patient/examplePatientRecord" ] ;
        fhir:l :examplePatientRecord # OPTIONAL resource link
    ] ;
    # Re-interpretation of concept IRI. Coding omitted for brevity.
    fhir:code [
        # 'is about' from Information Artifact Ontology
        obo:IAO_0000136 :exampleTinnitusFinding ;
    ] .

# 'Tinnitus (finding)' from SNOMED
:exampleTinnitusFinding a sct:60862001 . 

# 'tinnitus' from Human Phenotype Ontology
:exampleTinnitus a obo:HP_0000360 .

# Alternative, non-specific terminology mapping
sct:60862001 skos:relatedMatch obo:HP_0000360 . 


# Associated Patient and Person records
:examplePatientRecord a fhir:Patient .

:examplePersonRecord a fhir:Person ;
    fhir:link [
        fhir:target [
            fhir:l :examplePatientRecord ;
            fhir:reference [ fhir:v "Patient/examplePatientRecord" ] ;
        ] ;
    ] .


# Monotonic mapping to ontologies
:examplePatientRecord a obo:OBI_0000078 ; # 'eMedical Record' from Ontology for Biomedical Investigations
   # 'is about' 
   obo:IAO_0000136 :examplePerson .

:examplePersonRecord a obo:OBI_0000078 ; # 'eMedical Record' from Ontology for Biomedical Investigations
    # 'is about'
    obo:IAO_0000136 :examplePerson .

:examplePerson a obo:MF_0000016 ; # 'human being' from Mental Functioning Ontology
    # 'has role' from Relations Ontology
    obo:RO_0000087 [ 
        a obo:OBI_0000093 ; # 'patient role' from Ontology for Biomedical Investigations
    ] ;
    # 'participates in' from Relations Ontology
    obo:RO_0000056 :exampleTinnitusFinding ;
    # 'has phenotype' from Relations Ontology
    obo:RO_0002200 :exampleTinnitus .