json-schema-validation.md

JSON Schema validation

When dealing with data, the information is abstracted into a given structure, data are then pieces of information. In any application, the data can be semantically present in more than one and different structures, for instance, the database holds the application data with a structure that is not necessarily the same structure that the data is exposed in the web interface, but the data is still the same.

The more transformations, more complicated, as you have imagined. What happens in these transformations is a lot of code. There is the server-side with databases and integrations, there is the client-side with web, mobile, and many other applications. Many different ways to make all data transformations in all these different places.

The schema is the rules that configures the data structure. In JSON for instance, the data belongs to pieces called members. A member have the name and other properties, most important the type, that can be string, object or array, the schema defines that among other rules.

Let’s see some code.

The given JSON:

{
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York"
  },
  "phoneNumber": [
    {
      "location": "home",
      "code": 44
    }
  ]
}

The Schema that validates the data and structure of previous JSON:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "streetAddress": {
          "type": "string"
        },
        "city": {
          "type": "string"
        }
      },
      "required": [
        "streetAddress",
        "city"
      ]
    },
    "phoneNumber": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string"
          },
          "code": {
            "type": "integer"
          }
        },
        "required": [
          "location",
          "code"
        ]
      }
    }
  },
  "required": [
    "address",
    "phoneNumber"
  ]
}

Damn, looks crazy, right? Don’t worry, there is plenty of implementations here http://json-schema.org/implementations.html that can be useful. Also many other ways to test and validate data structures, a good example is https://github.com/hapijs/joi/, what changes is the language used, the standard JSON Schema is a valid JSON, Joi uses a much more friendly functional notation.

So what?

The tooling is a details, this is much more about the workflow. Teams make progress in different speeds and directions, doing schema validation allows teams in different edges to rely in a document that express all the underlying transformations that is, important, currently valid. The document is the Schema, the good thing in using standard schema is the possibility to expose in the same channel as the data.

Let’s imagine the scenario of a big project that have many client and server interfaces, but mainly what we know is what is exposed in a single channel, and for that is used a REST API. So in the workflow, folks in different teams provides and consumes from a single place. Each developer and tester need to know for sure that the interface they are work in is updated with the consumed data, so the data provider also provide the schema, and the consumer, that can be a web app for instance, will detect changes made in the data source and invalidade incompatible code.