FHIR and GraphQL

this page contains early/provisional notes related to the development of a standard approach for use of graphQL with FHIR.

Note: this page anticipates community agreement around a standard interoperable graphql interface for FHIR servers. There is always other ways to use graphQL with FHIR, which are useful and valid, *and are not prohibited* (if they are other end-points).

For discussion, see [chat.fhir.org]

Goals

The graphql functionality should be described by a schema

Invoking GraphQL

For reasons of consistency with other aspects of FHIR, the standard end points for graphQL are

[base]/$graphql
[base]/[Type]/[id]/$graphql

GraphQL can be invoked by get with a query parameter, or a POST with the graphQL as the body, or a JSON body. (see [[1]].

The mime type of the response is application/json. Non JSON responses are not described by the specification.

Invocation Context

• System level ([base]/$graphql) - the query must start by selecting a resource type and some search criteria (see below)
• Resource Instance level ([base]/[Type]/[id]/$graphql) - the query assumes a single resource is in scope

Data type mappings

Primitive Data types:

• GraphQL Type | FHIR Type
• Int | integer, positiveInt, unsignedInt
• Float | decimal
• Boolean | boolean
• ID | id
• String | everything else

Complex Data Types:

• Names are unchanged

Error handling

Servers SHALL return an error when fields that do not exist are used, or when arguments, types, directives that are not recognised or supported are encountered

Field Selection

Any FHIR defined field can be used directly e.g. this graphql against the Patient resource (r3)

{ 
 name { text given family } 
}

Polymorphic fields are represented by their JSON property name E.g. for Observation.value[x]:

{ 
 valueQuantity { value units } 
}

Note: This is because the leafs names have to correspond to scalar types, so there is no use selecting all the variants at once

Field Arguments

Primitive fields SHALL not have any arguments at all.

Complex fields may have one of more of the following parameters:

• "fhirpath" - a fhir path statement selecting which of the subnodes is to be included. e.g.

{ 
 name(fhirpath: "family.exists()") { text given family } 
}

• "[field]" - the name of a sub-property with a specified value that must be matched for the field to be included. e.g.

{ 
 name(use: official) { text given family } 
}

Additional Selectors

An object of type reference can have an additional selection "resource". This is an instruction to the server to resolve the reference, and then include the contents of the resource as specified by sub-selections in the property name "resource" (can be aliased).

e.g. On Observation:

{ 
   subject { reference, resource {active} } 
}

The resource selector has two arguments:

• optional : true | false. (default is false). If the server cannot resolve the reference, and optional is not true, the server returns an error instead of the graph output
• type : [Resource] - only selects resources of a particular type. Note that this is similar in effect to

{ 
 id
 subject { 
  reference
   resource {
     ...on Patient {
         birthDate
   }
   ...on Practioner {
       practitionerRole {  speciality }
   }
 }  
 code {coding {system code} }
}

but slightly denser:

{ 
 id
 subject { 
  reference
   resource(type : Patient) { birthDate }
   resource(type : Practioner) { practitionerRole {  speciality } }
 }  
 code {coding {system code} }
}

Searching resources

global system scope... todo...

open questions

• How to do polymorphic fields
• how to do reverse references (e.g. include resources that reference the one in focus)
• polymorphic fields
• need for directives?
• extensions in primitive fields / schema reconciliation
• searching resources (.e.g context [base]/$graphql)
• backwards reference resolution
• mutations