JSON at Work

Chapter 5. JSON Schema

We’ve covered the basics of JSON using our core platforms (JavaScript, Ruby on Rails, and Java), and now it’s time to wade in deeper. In this chapter, we’ll show how to leverage JSON Schema to define the structure and format of JSON documents exchanged between applications:

• JSON Schema overview

• Core JSON Schema—basics and tooling

• How to design and test an API with JSON Schema

In our examples, we’ll design an API with JSON Schema after we progressively walk through the concepts of JSON Schema. As noted in the preface, from now on we will write all our examples in Node.js to keep the size of the chapters to a minimum. But know that the other platforms work well with JSON Schema. If you haven’t installed Node.js already, now would be a great time. Follow the instructions in Appendix A.

JSON Schema Overview

Many architects and developers are unfamiliar with JSON Schemas. Before going into details, it’s important to know what a JSON Schema is, how it helps, and why/when to use it. Along the way, we’ll look at the JSON Schema Specification and show a simple example.

What Is JSON Schema?

A JSON Schema specifies a JSON document (or message)’s content, structure, and format. A JSON Schema validates a JSON document, so you may be wondering why plain JSON validation isn’t enough. Unfortunately, validation is an overloaded term.

Syntactic Versus Semantic Validation

The difference is in the type of validation. When you validate a JSON document without a Schema, ...