6 Reasons why JSON Schema is worth your time

Today, we're diving into the wonderful world of JSON schema, and I'm going to give you 6 reasons why I think it's worth your time.

Sometimes, by the time JSON schema is considered in software projects it's seen as an impediment to going fast. I'd like to counter that argument by saying that, yes, creating schemas for your data may seem to slow things down at first. But once you have a canonical source of truth for each resource you're dealing with, the subsequent effort can reduce drastically. Here's some reasons why:

1. Data validation

This is the obvious one. JSON schema is going to ensure that our data adheres to specific structures, uses the right data types, and obeys the constrains set out in the schema.

In the JavaScript ecosystem we can use the excellent AJV package to validate any JavaScript object against a JSON schema. This is especially useful to ensure that API contracts are maintained when communicating with other services.

2. Automatic UI generation

Sometimes we might know the data we want to collect, and now we need to create a UI to collect it. By starting with a JSON schema we can use React JSON schema Form (Rjsf) to automatically generate forms with prebuilt client and server-side validation against the provided schema.

Rjsf makes it trivial to quickly spin up everything needed to begin capturing data. All we need to provide is a schema. It also allows for a high level of customisation for more complex use cases.

See their playground app for examples of creating schema driven forms in no time.

3. Type generation

Let's say we've built a Typescript service that takes some input data. We're likely going to create types that represent that input data.

By having a JSON schema, not only can we validate the input data, but we can generate the Typescript types automatically from the schema.

The schemas can evolve as the data structure changes. When we update our JSON schema, we can regenerate the TypeScript types to reflect those changes automatically, ensuring that our code always aligns with our data structures and increasing the maintainability of the application.

We can also generate JSON schema from our Typescript types. Useful if we have types but no schema, or we would prefer to have the types as our source of truth.

Here are some packages to help with generation:

• JSON Schema to Typescript
• Typescript to JSON Schema

4. OpenAPI Spec generation

OpenAPI is a specification for HTTP APIs that allows us to define how our APIs behave. A schema for APIs, if you will.

The key difference between JSON schema and OpenAPI is that a JSON schema defines JSON data, whereas OpenAPI describes the entire API (the endpoints, input parameters) including the data.

OpenAPI, like JSON schema can seem like a drag to implement if we're not using it already. However, if we start with JSON schema we can use this handy library to generate the OpenAPI Schema Object which is used to define the input and output data types.

5. Generate fake data

Let's say we've built an application that exposes some data via an API called by other applications. In order to test the integration between our application and the outside world we need to provide a sample of the output data from our application. Oftentimes this might be a sample of JSON maintained by us, or worse it's a sample of JSON maintained by the owners of the other application. This is not ideal because it relies on us humans informing each other when the contract changes.

With tools like JSON schema Faker we can generate fake data that is always consistent with our schema. Meaning that as soon as our schema changes, our fake data does too. This can be used in conjunction with consumer-driven contracts to ensure that breaking changes to our integrations with other applications are caught early.

6. JSON schemas in the IDE

This is the "one more thing" point which drove me to write this whole post.

Given a JSON schema, VSCode can provide autocomplete, error highlighting and validation for JSON or YAML files.

Recently I worked on a complex low/no-code application configured using YAML files. The people writing the configuration were not engineers and relied on an increasingly complicated set of documentation to be able to correctly configure the system.

Using JSON schemas inside of VSCode allowed the configuration team to leverage the autocomplete capabilities of the IDE to help them make fewer mistakes when configuring the system.

In order to set this up, we need to specify the JSON schema files and associate them with particular filename patterns.

Open the Settings tab, search for "JSON schemas" and choose "Edit in settings.json"

From the settings.json we can add either a yaml.schemas or a json.schemas block depending on the file types we wish to use.

For YAML

  "yaml.schemas": {
    "/absolute/path/to/your/json/schema.json": "somefile.yaml" // a file pattern can be used here
}

For JSON

"json.schemas": [
  {
    "fileMatch": [
      "somefile.json" // a file pattern can be used here
    ],
    "url": "file:/absolute/path/to/your/json/schema.json"
  }
]

Save the settings.json and reload VSCode. When we open a file that matches the pattern specified in the configuration the IDE will use the schema to validate the file contents 🎉

As we've seen there are many benefits to creating and using JSON schemas when dealing with JSON data in your applications. By starting with the schema, we can generate code to deal with input, validation, testing and more.

Thanks for reading!