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 recognized 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 leaf names have to correspond to scalar types, so there is no use selecting all the variants at once

Extensions on primitives: the JSON convention for primitives is observed. e.g. use _[name] for accessing extensions on primitives.

So

{
 subject { resource { birthDate _birthDate { extension {valueDateTime} } } }
}

results in

{
 "subject":[{
   "resource":{
     "birthDate":"2016-05-18",
     "_birthDate":{
       "extension":[{
         "valueDateTime":"2016-05-18T10:28:45Z"
       }]
     }
   }
 }]
}

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

Resource references

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 (e.g. resource does not exist, or user security rights or choices do not permit resource to be seen), 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} }
}

Clients can use either approach - type selection as a parameter, of using a fragment type condition - the first is shorter while the second aligns with schema

Searching resources

When a graphQL statement is run at the system level, rather than against a particular resource, the first thing the query must do is select the resource(s) of interest. The logic of this follows the FHIR search API, but reimplements in a graphQL centric way.

There are 2 ways to query, a simple and a full API. In the simple way, the client simply asks for a list of resources:

{ 
  Condition(clinical_status: relapse, patient: example) { id, clinicalStatus } 
}

This is a request to list all the Condition resources that have a status if 'relapsed' for the patient with id = example. The arguments are any of the search parameters defined on the specified resource. Note that the parameter's names are changed by replacing '-' in the name with '_' (for graphql syntax requirements) (FHIR defines parameters starting with _ but will never define search parameters starting with '-'). There is one additional possible argument, "fhirpath" which the server evaluates on all the possible matches.

The output of this is a list:

{
  "Condition" [{ 
    "id" : "100",
    "clinicalStatus" : "relapse",
  },{ 
    "id" : "100",
    "clinicalStatus" : "relapse",
  }]
}

Servers may reject the request if there are too many matches. If they do so, they SHALL return an error indicating that the query could not be fulfilled. (rather than silently filtering the list).

The simplest case for search is when an id is provided:

{ 
  Condition(id: cexample) { id, clinicalStatus } 
}

This is a request to fetch a single resource with a known id. This equates to a search with the parameter _id. Typically, no other search parameters are provided (not relevant).

 todo: is the response an array in json on this case?

The following search parameters are not supported on the graphQL interface: _include, _revinclude, _contained, _containedType

Rather than the simple list approach, clients are able to request a Connection based approach (based on http://graphql.org/learn/pagination/, but adapted to the existing FHIR Search API).

{ 
  ConditionConnection (clinical_status: active, patient: example) { 
    count offset pagesize
    edges {
      id, clinicalStatus
    }
    first previous next last
  } 
}

The arguments are the same as for the simple case, with the addition of the special argument 'cursor' (see below). The server returns a connection object that contains information about the search, along with a list of 'edges' which are the actual matches.

{
 "ConditionConnection" : {
   "count": 50,
   "offset" : 0,
   "pageSize" : 25,
   "next" : "45f9ada8-db37-4498-ba7d-75a044668387"
   "edges" : [{ 
    "id" : "100",
    "clinicalStatus" : "relapse",
  },{ 
    "id" : "100",
    "clinicalStatus" : "relapse",
  }]
 }
}

The client can follow up on the first/previous/next/last links using the argument 'cursor':

{ 
  ConditionConnection (cursor : "45f9ada8-db37-4498-ba7d-75a044668387") { 
    count offset pagesize
    edges {
      id, clinicalStatus
    }
    first previous next last
  } 
}

The client can not change the parameters for the search (and should not specify them) when providing a cursor. The value of the token is opaque to the client, and only understood by the server.

Note that when using the fhirpath argument with Connection based searches, the server may choose to apply the fhirpath filter after the search paging is performed, so that individual pages may be shorter (or empty).

Reverse References

It's also possible to use search is a special mode, doing reverse lookups - e.g. list all the resources that refer to this resource. An example of this use is to look up a patient, and also retrieve all the Condition resources for the patient.

This is a special case of search, above, but with an additional mandatory parameter "_reference". For example:

{
  name { [some fields] }
  Condition(_reference: patient) {
   [some fields from Condition]
  }
}

There must be at least the argument "_reference" which identifies which of the search parameters for the target resource is used to match the resource that has focus. In addition, there may be other arguments as defined above in search (except that the "id" argument is prohibited here as non-sensical)

The response for the query above would be

{

 "name: [ [some fields] ],
 "Condition" : [
   { [some fields from matching Condition resource] }
 ]

}

The "connection" based search option is also supported, as described above. If the client wishes to pursue any of the cursor based links in the graphQL results it asks for back, then it initiates this a new separate query as defined above, rather than repeating the nested query. I.e. the 'cursor' argument is prohibited, except at the root of query.

open questions

• need for directives?
• generate schema
• searching resources (.e.g context [base]/$graphql)
• mutations