Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 39 ยท JSON Schema

JSON Schema: An Introduction

Learn what JSON Schema is, why it beats hand-written checks, how a schema describes a document, and how to validate data with a runnable mini validator and clear error messages.

JSON is flexible: it will happily carry {"age": "banana"}. That freedom is a problem when a program expects an age that is a number between 0 and 150. JSON Schema is a vocabulary, itself written in JSON, for describing what a valid document looks like. A validator then checks any document against the schema and reports every violation.

Schemas are useful in four places: validating API requests and responses, checking config files, generating forms and documentation, and driving editor autocomplete.

The runner on this site has no JSON Schema library, so the lessons use a compact validator written for this course. It implements the keywords taught here and is a stand-in for real validators such as Ajv (JavaScript), jsonschema (Python) or networknt (Java). The schemas themselves are standard.

Your first schema

A schema is a JSON object. The keywords you meet first:

  • $schema: which version of the specification the schema uses (we use Draft 2020-12).
  • title and description: documentation for people.
  • type: the JSON type the value must have.
  • properties: schemas for named object keys.
  • required: which keys must be present.
JSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Person",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name"]
}

Read it aloud: "A person is an object. It may have a string name and an integer age. The name is required."

Validating with the mini validator

The code below defines the validator (you will reuse it in the next lessons) and checks four documents against the Person schema. Every error carries a path such as $.age, which points to the bad value.

Node.js Validate documents against a schema

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Two behaviors are worth noticing. First, all errors are reported, not just the first. Second, unknown extra properties are allowed by default: a schema only restricts what it mentions.

Open by default

JSON Schema is "open world": anything not forbidden is allowed. That makes schemas easy to evolve, but typos slip through ("nmae": "Lena" is fine if only name is optional). You close the object with additionalProperties: false, covered in objects and arrays.

Node.js Open versus closed objects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Schema as documentation

Because a schema is data, tools can read it. An API documentation page can list each property with its type and whether it is required.

Node.js Generating docs from a schema

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Versions

JSON Schema has several drafts: draft-04, draft-06, draft-07, 2019-09 and 2020-12. Details differ (for example items for tuples became prefixItems in 2020-12). Always declare $schema, and check which draft your validator supports.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a JSON Schema itself written in?

    A schema is an ordinary JSON document, which is why tools can read and generate it.
  2. 2. By default, what happens to a property the schema does not mention?

    JSON Schema is open by default; use additionalProperties false to forbid extras.
  3. 3. Which keyword lists the properties that must be present?

    required takes an array of property names.
  4. 4. What does the $schema keyword do?

    It identifies the specification version so validators interpret keywords correctly.

Summary

  • JSON Schema describes valid JSON documents using JSON itself.
  • type, properties and required cover the basics; unknown properties are allowed unless forbidden.
  • A validator reports a path and a message for each violation.
  • Always declare the draft in $schema.

Next: Types and constraints