This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "FHIR and GraphQL"

From HL7Wiki
Jump to navigation Jump to search
Line 169: Line 169:
 
   ]
 
   ]
 
}
 
}
 +
 +
todo: do we need to worry about there being too many matching resources?
  
 
== Searching resources ==
 
== Searching resources ==

Revision as of 02:23, 22 May 2017

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

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, 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} }
}

Reverse References

It's also possible to do reverse look ups - 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. The syntax for this is to list the resource type as a field. For example:

{
  name {...}
  Condition(_reference: patient) {
   .. fields from Condition ...
  }
}

When used like this, the reverse reference field must have at least argument "_reference" which identifies which of the search parameters is used to match the resource that has focus. In addition, there may be other arguments:

  • [search] - other search parameters on the resource to apply as further filters
  • fhirpath - a condition that must be true in the matching resources for them to be included

The response for the query above would be

{

 "name: [.. details..],
 "Condition" : [
   { ...details of Condition resource...}
 ]

}

todo: do we need to worry about there being too many matching resources?

Searching resources

global system scope... todo...

open questions

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