Reference

The basics

In What is a schema?, we described what a schema is, and hopefully justified the need for schema languages. Here, we proceed to write a simple JSON Schema.

Hello, World!

When learning any new language, it's often helpful to start with the simplest thing possible. In JSON Schema, an empty object is a completely valid schema that will accept any valid JSON.

schema
{}
Copy

This accepts anything, as long as it's valid JSON

data
42
Copy
compliant to schema
data
"I'm a string"
Copy
compliant to schema
data
{ "an": [ "arbitrarily", "nested" ], "data": "structure" }
Copy
compliant to schema
New in draft 6

You can also use true in place of the empty object to represent a schema that matches anything, or false for a schema that matches nothing.

This accepts anything, as long as it's valid JSON:

schema
true
Copy
data
42
Copy
compliant to schema
data
"I'm a string"
Copy
compliant to schema
data
{ "an": [ "arbitrarily", "nested" ], "data": "structure" }
Copy
compliant to schema

Documents for this schema will always be invalid:

schema
false
Copy
data
"Resistance is futile... This will always fail!!!"
Copy
not compliant to schema

The type keyword

Of course, we wouldn't be using JSON Schema if we wanted to just accept any JSON document. The most common thing to do in a JSON Schema is to restrict to a specific type. The type keyword is used for that.

When this book refers to JSON Schema "keywords", it means the "key" part of the key/value pair in an object. Most of the work of writing a JSON Schema involves mapping a special "keyword" to a value within an object.

For example, in the following, only strings are accepted:

schema
{ "type": "string" }
Copy
data
"I'm a string"
Copy
compliant to schema
data
42
Copy
not compliant to schema

The type keyword is described in more detail in here.

Declaring a JSON Schema

It's not always easy to tell which draft a JSON Schema is using. You can use the $schema keyword to declare which version of the JSON Schema specification the schema is written to. See $schema for more information. It's generally good practice to include it, though it is not required.

For brevity, the $schema keyword isn't included in most of the examples in this book, but it should always be used in the real world.

schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema" }
Copy
Draft-specific info
In Draft 4, a $schema value of http://json-schema.org/schema# referred to the latest version of JSON Schema. This usage has since been deprecated and the use of specific version URIs is required.

Declaring a unique identifier

New in draft 6

It is also best practice to include an $id property as a unique identifier for each schema. For now, just set it to a URL at a domain you control, for example:

schema
{ "$id": "http://yourdomain.com/schemas/myschema.json" }
Copy

The details of $id become more apparent when you start structuring a complex schema.

Draft-specific info
In Draft 4, $id is just id (without the dollar-sign).

Need help?

Learning JSON Schema is often confusing, but don't worry, we are here to help! You can start a thread on GitHub Discussions, connect with us on Slack, or join our live Office Hours.
We'd love to help!! ❤️