#FHIR and HTTP Patch

Jan 31, 2016

At the last connectathon, we had a stream testing support for PATCH using JSON patch. A number of us participated in the stream, and some of us got JSON patch working fine. But it’s not clear that JSON Patch is the solution we’re looking for.  JSON Patch has some advantages:

  • It’s an external standard - we like that
  • It’s pretty simple - we like that too
  • There’s existing libraries, and set of test cases - we really like that

But. The problem is that JSON patch is based on JSONPointer - when you specify changes in a list of objects, you specify the list by the numerical offset of the object in it. This means that in order to make a set of changes to a set of JSON objects, you must know exactly what the existing content is. So in order to use JSON patch, you must first query a resource for it’s latest state, determine the changes that you wish to make, and apply them using a version specific  update.

Sure, that sequence works. But it doesn’t really deliver on the 2 key use cases that people have identified for using PATCH in FHIR:

  • Save a client from fetching an entire resource to make updates to it
  • Manage more effectively updates when the client doesn’t have access to all the parts of a resource

The second case is interesting. The problem is that when a server gets an update from the client, to figure out how to use it, it must determine what the client has access to; if the client hasn’t get access to it, it can’t delete content that the client hasn’t mentioned in the update. Tricky. But because JSON Patch using list index offsets, it turns out that the basic processing logic isn’t any different - the server must determine what the client has access to in order to figure that out.

There’s one other problem with the JSON Patch approach - it doesn’t support XML, and there’s lots of FHIR implementers using XML.

FHIR Patch

There’s an alternative approach that might be better. Instead of using index based offsets, allow a general query. And use the FHIR parameters infrastructure, to support both JSON and XML.

I would propose a smaller set of operations, but they have different parameters:

  • Add - content to add
  • Remove - selection query (using FHIRPath)
  • Replace - selection query (using FHIRPath) + content to add
  • Test - query that must evaluate to true

Note: I’ll be making another blog post shortly about where FHIRPath is up to. 

This is more capable than the JSON patch approach - you can specify a change to make without first having to get the resource. For instance, you could say, if the patient doesn’t have this phone number, then add it.

But this has some disadvantages too:

  • there’s no external libraries support for this
  • it needs FHIRPath. while I think that everyone will eventually need to support this, so far, there’s no particular need to for a lot of implementers
  • It’s much more complex to test

There was some discussion around this during the connectathon, but there was no clear preference amongst the participants. None of use like these disdvantages, but we don’t really like the limitations either. Comments are welcome.