JSON schema design for variable response

Question

I am drafting a JSON schema for an API. One of the responses aims to show all the updates to different properties of an given entity. The number of updates may vary from one response to another. For example, it can be that the values of property_a and property_d change in one response, and those of property_a, property_b, and property_c in the next.

I want to design a schema that is both friendly to human interpretation and programmatic execution.

A concrete example of such an entity can be appointment bookings. Each appointment may consist of a place, a date, a time and a list of attendees, and all of them may change after an appointment is created. Now we want to have an API endpoint that would return any update to an existing appointment. The response contains the updated properties only.

So far I come up something like below:

{
    "event": "update",
    "appointment_id": 123,
    "updated_properties": ["place", "time"],
    "place": "some new location",
    "time": "some new time"
}

In essence, this schema tells which properties are updated and simply returns these properties only with their new values.

Is this a sensible design? Any alternative schema for improvements?

Answer 1

You could consider changing the value for updated_properties to an object instead of an array and list the new value right in the list of updated properties. This will reduce the overall size of the message.

{
    "event": "update",
    "appointment_id": 123,
    "updated_properties: {
        "place": "some new location",
        "time": "some new time"
    },
    "added_properties": {
        "attendees": [{"name": "Some Name", "role": "organizer"}]
    }
}

The response you're describing sounds to be from a POST or PUT request, so you could also simply list the updated/added properties in the object, stating in the documentation that all object properties are not returned, only the updated properties. The user could perform a GET request to get all the properties if needed.

{
    "event": "update",
    "appointment_id": 123,
    "place": "some new location",
    "time": "some new time",
    "attendees": [{"name": "Some Name", "role": "organizer"}]
}

Either approach would be acceptable.

Answer 2

You could use JSON Patch to represent changes to an entity. I'd suggest separating current state from it's "change history"

There are libraries for common programming languages to help you generate the patches

An example:

The resource:

GET /appointments/123
Last-Modified: Sun, 07 Aug 2016 07:00:00 GMT

{
    "appointment_id: 123,
    "place": "some new location",
    "time": "some new time"
}

Endpoint for changes:

GET /appointments/123/history?limit=1

[
  {
    date: '2016-08-07T07:00:00Z',
    change: [
      { "op": "replace", "path": "/time", "value": "som new time" },
      { "op": "add", "path": "/place", "value": "some new locatin" }
    ]
  }
]