Understanding JSONSchema

Understanding JSON Schema
Release 6.0
Michael Droettboom, et al
Space Telescope Science Institute
Nov 09, 2018

Contents
1 Conventions used in this book 3

1.1 Language-specific notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Draft-specific notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 What is a schema? 7
3 The basics 11
3.1 Hello, World! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 The type keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Declaring a JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.4 Declaring a unique identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4 JSON Schema Reference 15

4.1 Type-specific keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.1 Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.2 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.2.3 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.3 Numeric types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.1 integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.2 number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3.3 Multiples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.3.4 Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.4 object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.4.2 Required Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.4.3 Property names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.4.4 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.5 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4.6 Pattern Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.5 array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.5.1 Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.5.2 Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.5.3 Uniqueness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.6 boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.7 null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
i
4.8 Generic keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.8.1 Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.8.2 Enumerated values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.8.3 Constant values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.9 Combining schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.9.1 allOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.9.2 anyOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.9.3 oneOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.9.4 not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.10 The $schema keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.10.1 Advanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.11 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.11.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5 Structuring a complex schema 59

5.1 Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.1 Recursion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.2 The $id property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.2.1 Using $id with $ref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.3 Extending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6 Acknowledgments 67
Index 69
ii
Understanding JSON Schema, Release 6.0
JSON Schema is a powerful tool for validating the structure of JSON data. However, learning to use it by reading its
specification is like learning to drive a car by looking at its blueprints. You don’t need to know how an electric motor
fits together if all you want to do is pick up the groceries. This book, therefore, aims to be the friendly driving instructor
for JSON Schema. It’s for those that want to write it and understand it, but maybe aren’t interested in building their
own car—er, writing their own JSON Schema validator—just yet.
Note: This book describes JSON Schema draft 6. The most recent version is draft 7 — stay tuned, updates are coming!
Earlier and later versions of JSON Schema are not completely compatible with the format described here.
Where to begin?
• This book uses some novel conventions (page 3) for showing schema examples and relating JSON Schema to
your programming language of choice.
• If you’re not sure what a schema is, check out What is a schema? (page 7).
• The basics (page 11) chapter should be enough to get you started with understanding the core JSON Schema
Reference (page 15).
• When you start developing large schemas with many nested and repeated sections, check out Structuring a
complex schema (page 59).
• json-schema.org has a number of resources, including the official specification and tools for working with JSON
Schema from various programming languages.
• jsonschema.net is an online application run your own JSON schemas against example documents. If you want to
try things out without installing any software, it’s a very handy resource.
Contents 1
2 Contents
CHAPTER 1
Conventions used in this book
1.1 Language-specific notes

The names of the basic types in JavaScript and JSON can be confusing when coming from another dynamic language.
I’m a Python programmer by day, so I’ve notated here when the names for things are different from what they are in
Python, and any other Python-specific advice for using JSON and JSON Schema. I’m by no means trying to create a
Python bias to this book, but it is what I know, so I’ve started there. In the long run, I hope this book will be useful
to programmers of all stripes, so if you’re interested in translating the Python references into Algol-68 or any other
language you may know, pull requests are welcome!
The language-specific sections are shown with tabs for each language. Once you choose a language, that choice will be
remembered as you read on from page to page.
For example, here’s a language-specific section with advice on using JSON in a few different languages:
Python
In Python, JSON can be read using the json module in the standard library.
Ruby
In Ruby, JSON can be read using the json gem.
For C, you may want to consider using Jansson to read and write JSON.
1.2 Draft-specific notes

The JSON Schema standard has been through a number of revisions or “drafts”. The most important are Draft 6, the
most recent at the time of this writing, and Draft 4, on which a lot of production software was built, and the draft for
3
which an earlier version of this book was written.

The text is written to encourage the use of Draft 6 and gives priority to the latest conventions and features, but where it
differs from Draft 4, those differences are highlighted in special call-outs. If you only wish to target Draft 6, you can
safely ignore those sections.
New in draft 6
Draft 4
This is where anything pertaining to an old draft would be mentioned.
1.3 Examples
There are many examples throughout this book, and they all follow the same format. At the beginning of each example
is a short JSON schema, illustrating a particular principle, followed by short JSON snippets that are either valid or
invalid against that schema. Valid examples are in green, with a checkmark. Invalid examples are in red, with a cross.
Often there are comments in between to explain why something is or isn’t valid.
Note: These examples are tested automatically whenever the book is built, so hopefully they are not just helpful, but
also correct!
For example, here’s a snippet illustrating how to use the number type:
{ json schema }
{ "type": "number" }
!
42
!
-1
Simple floating point number:

!
5.0
Exponential notation also works:

!
2.99792458e8
Numbers as strings are rejected:
4 Chapter 1. Conventions used in this book

%
"42"
1.3. Examples 5
6 Chapter 1. Conventions used in this book

CHAPTER 2
What is a schema?
If you’ve ever used XML Schema, RelaxNG or ASN.1 you probably already know what a schema is and you can
happily skip along to the next section. If all that sounds like gobbledygook to you, you’ve come to the right place. To
define what JSON Schema is, we should probably first define what JSON is.
JSON stands for “JavaScript Object Notation”, a simple data interchange format. It began as a notation for the world
wide web. Since JavaScript exists in most web browsers, and JSON is based on JavaScript, it’s very easy to support
there. However, it has proven useful enough and simple enough that it is now used in many other contexts that don’t
involve web surfing.
At its heart, JSON is built on the following data structures:
• object:
{ "key1": "value1", "key2": "value2" }
• array:
[ "first", "second", "third" ]
• number:
42
3.1415926
• string:
"This is a string"
• boolean:
true
false
• null:
7
null
These types have analogs in most programming languages, though they may go by different names.
Python
The following table maps from the names of JavaScript types to their analogous types in Python:
JavaScript Python
string string
number int/float
object dict
array list
boolean bool
null None
45
4 Since JavaScript strings always support unicode, they are analogous to unicode on Python 2.x and str on Python 3.x.
5 JavaScript does not have separate types for integer and floating-point.
Ruby
The following table maps from the names of JavaScript types to their analogous types in Ruby:
JavaScript Ruby
string String
number Integer/Float
object Hash
array Array
boolean TrueClass/FalseClass
null NilClass
With these simple data types, all kinds of structured data can be represented. With that great flexibility comes great
responsibility, however, as the same concept could be represented in myriad ways. For example, you could imagine
representing information about a person in JSON in different ways:
{
"name": "George Washington",
"birthday": "February 22, 1732",
"address": "Mount Vernon, Virginia, United States"
}
{
"first_name": "George",
(continues on next page)
8 Chapter 2. What is a schema?

(continued from previous page)

"last_name": "Washington",
"birthday": "1732-02-22",
"address": {
"street_address": "3200 Mount Vernon Memorial Highway",
"city": "Mount Vernon",
"state": "Virginia",
"country": "United States"
}
}
Both representations are equally valid, though one is clearly more formal than the other. The design of a record will
largely depend on its intended use within the application, so there’s no right or wrong answer here. However, when
an application says “give me a JSON record for a person”, it’s important to know exactly how that record should be
organized. For example, we need to know what fields are expected, and how the values are represented. That’s where
JSON Schema comes in. The following JSON Schema fragment describes how the second example above is structured.
Don’t worry too much about the details for now. They are explained in subsequent chapters.
{ json schema }
{
"type": "object",
"properties": {
"first_name": { "type": "string" },
"last_name": { "type": "string" },
"birthday": { "type": "string", "format": "date-time" },
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" },
"country": { "type" : "string" }
}
}
}
}
By “validating” the first example against this schema, you can see that it fails:
%
{
"name": "George Washington",
"birthday": "February 22, 1732",
"address": "Mount Vernon, Virginia, United States"
}
However, the second example passes:
9
!
{
"first_name": "George",
"last_name": "Washington",
"birthday": "22-02-1732",
"address": {
"street_address": "3200 Mount Vernon Memorial Highway",
"city": "Mount Vernon",
"state": "Virginia",
"country": "United States"
}
}
You may have noticed that the JSON Schema itself is written in JSON. It is data itself, not a computer program. It’s just
a declarative format for “describing the structure of other data”. This is both its strength and its weakness (which it
shares with other similar schema languages). It is easy to concisely describe the surface structure of data, and automate
validating data against it. However, since a JSON Schema can’t contain arbitrary code, there are certain constraints
on the relationships between data elements that can’t be expressed. Any “validation tool” for a sufficiently complex
data format, therefore, will likely have two phases of validation: one at the schema (or structural) level, and one at
the semantic level. The latter check will likely need to be implemented using a more general-purpose programming
language.
10 Chapter 2. What is a schema?

CHAPTER 3
The basics
In What is a schema? (page 7), we described what a schema is, and hopefully justified the need for schema languages.
Here, we proceed to write a simple JSON Schema.
3.1 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.
{ json schema }
{ }
This accepts anything, as long as it’s valid JSON

!
42
!
"I'm a string"
!
{ "an": [ "arbitrarily", "nested" ], "data": "structure" }
New in draft 6
11
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.
{ json schema }
true
This accepts anything, as long as it’s valid JSON

!
42
!
"I'm a string"
!
{ "an": [ "arbitrarily", "nested" ], "data": "structure" }
{ json schema }
false
%
"Resistance is futile... This will always fail!!!"
3.2 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.
Note: 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:
{ json schema }
{ "type": "string" }
12 Chapter 3. The basics

!
"I'm a string"
%
42
The type keyword is described in more detail in Type-specific keywords (page 15).
3.3 Declaring a JSON Schema

Since JSON Schema is itself JSON, it’s not always easy to tell when something is JSON Schema or just an arbitrary
chunk of JSON. The $schema keyword is used to declare that something is JSON Schema. It’s generally good practice
to include it, though it is not required.
Note: 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.
{ json schema }
{ "$schema": "http://json-schema.org/schema#" }
You can also use this keyword to declare which version of the JSON Schema specification that the schema is written to.
See The $schema keyword (page 55) for more information.
3.4 Declaring a unique identifier

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:
{ "$id": "http://yourdomain.com/schemas/myschema.json" }
The details of The $id property (page 63) become more apparent when you start Structuring a complex schema (page 59).
New in draft 6
Draft 4
In Draft 4, $id is just id (without the dollar-sign).
3.3. Declaring a JSON Schema 13

14 Chapter 3. The basics

CHAPTER 4
JSON Schema Reference
4.1 Type-specific keywords

The type keyword is fundamental to JSON Schema. It specifies the data type for a schema.
At its core, JSON Schema defines the following basic types:
• string (page 17)
• Numeric types (page 21)
• object (page 27)
• array (page 38)
• boolean (page 46)
• null (page 46)
These types have analogs in most programming languages, though they may go by different names.
15
Python
The following table maps from the names of JavaScript types to their analogous types in Python:
JavaScript Python
string string
number int/float
object dict
array list
boolean bool
null None
45
4 Since JavaScript strings always support unicode, they are analogous to unicode on Python 2.x and str on Python 3.x.
Ruby
The following table maps from the names of JavaScript types to their analogous types in Ruby:
JavaScript Ruby
string String
number Integer/Float
object Hash
array Array
boolean TrueClass/FalseClass
null NilClass
The type keyword may either be a string or an array:

• If it’s a string, it is the name of one of the basic types above.
• If it is an array, it must be an array of strings, where each string is the name of one of the basic types, and each
element is unique. In this case, the JSON snippet is valid if it matches any of the given types.
Here is a simple example of using the type keyword:
{ json schema }
!
42
16 Chapter 4. JSON Schema Reference

!
42.0
This is not a number, it is a string containing a number.

%
"42"
In the following example, we accept strings and numbers, but not structured data types:
{ json schema }
{ "type": ["number", "string"] }
!
42
!
"Life, the universe, and everything"
%
["Life", "the universe", "and everything"]
For each of these types, there are keywords that only apply to those types. For example, numeric types have a way of
specifying a numeric range, that would not be applicable to other types. In this reference, these validation keywords are
described along with each of their corresponding types in the following chapters.
4.2 string
The string type is used for strings of text. It may contain Unicode characters.
Python
In Python, "string" is analogous to the unicode type on Python 2.x, and the str type on Python 3.x.
Ruby
In Ruby, "string" is analogous to the String type.
4.2. string 17
{ json schema }
!
"This is a string"
Unicode characters:
!
"Déjà vu"
!
""
!
"42"
%
42
4.2.1 Length
The length of a string can be constrained using the minLength and maxLength keywords. For both keywords, the value
must be a non-negative number.
{ json schema }
{
"type": "string",
"minLength": 2,
"maxLength": 3
}
%
"A"

!
"AB"
!
"ABC"
%
"ABCD"
4.2.2 Regular Expressions

The pattern keyword is used to restrict a string to a particular regular expression. The regular expression syntax is the
one defined in JavaScript (ECMA 262 specifically). See Regular Expressions (page 56) for more information.
Note: When defining the regular expressions, it’s important to note that the string is considered valid if the expression
matches anywhere within the string. For example, the regular expression "p" will match any string with a p in it, such
as "apple" not just a string that is simply "p". Therefore, it is usually less confusing, as a matter of course, to surround
the regular expression in ^...$, for example, "^p$", unless there is a good reason not to do so.
The following example matches a simple North American telephone number with an optional area code:
{ json schema }
{
"type": "string",
"pattern": "^(\$[0-9]{3}\$)?[0-9]{3}-[0-9]{4}$"
}
!
"555-1212"
!
"(888)555-1212"
%
"(888)555-1212 ext. 532"
4.2. string 19
%
"(800)FLOWERS"
4.2.3 Format
The format keyword allows for basic semantic validation on certain kinds of string values that are commonly used.
This allows values to be constrained beyond what the other tools in JSON Schema, including Regular Expressions
(page 56) can do.
Note: JSON Schema implementations are not required to implement this part of the specification, and many of them
do not.
There is a bias toward networking-related formats in the JSON Schema specification, most likely due to its heritage in
web technologies. However, custom formats may also be used, as long as the parties exchanging the JSON documents
also exchange information about the custom format types. A JSON Schema validator will ignore any format type that it
does not understand.
Built-in formats
The following is the list of formats specified in the JSON Schema specification.
• "date-time": Date representation, as defined by RFC 3339, section 5.6.
• "email": Internet email address, see RFC 5322, section 3.4.1.
• "hostname": Internet host name, see RFC 1034, section 3.1.
• "ipv4": IPv4 address, according to dotted-quad ABNF syntax as defined in RFC 2673, section 3.2.
• "ipv6": IPv6 address, as defined in RFC 2373, section 2.2.
• "uri": A universal resource identifier (URI), according to RFC3986.
• "uri-reference": New in draft 6 A URI Reference (either a URI or a relative-reference), according to RFC3986,
section 4.1.
• "json-pointer": New in draft 6 A JSON Pointer, according to RFC6901. There is more discussion on the use
of JSON Pointer within JSON Schema in Structuring a complex schema (page 59). Note that this should be used
only when the entire string contains only JSON Pointer content, e.g. /foo/bar. JSON Pointer URI fragments,
e.g. #/foo/bar/ should use "uri" or "uri-reference".
• "uri-template": New in draft 6 A URI Template (of any level) according to RFC6570. If you don’t already
know what a URI Template is, you probably don’t need this value.
URI vs. URI reference
If the values in the schema the ability to be relative to a particular source path (such as a link from a webpage), it is
generally better practice to use "uri-reference" rather than "uri". "uri" should only be used when the path must
be absolute.
Draft 4
Draft 4 only includes "uri", not "uri-reference". Therefore, there is some ambiguity around whether "uri"
should accept relative paths.

4.3 Numeric types

There are two numeric types in JSON Schema: integer (page 21) and number (page 22). They share the same validation
keywords.
Note: JSON has no standard way to represent complex numbers, so there is no way to test for them in JSON Schema.
4.3.1 integer
The integer type is used for integral numbers.
Python
In Python, "integer" is analogous to the int type.
Ruby
In Ruby, "integer" is analogous to the Integer type.
{ json schema }
{ "type": "integer" }
!
42
!
-1
Floating point numbers are rejected:

%
3.1415926

%
"42"
Warning: The precise treatment of the “integer” type may depend on the implementation of your JSON Schema
validator. JavaScript (and thus also JSON) does not have distinct types for integers and floating-point values.
4.3. Numeric types 21

Therefore, JSON Schema can not use type alone to distinguish between integers and non-integers. The JSON
Schema specification recommends, but does not require, that validators use the mathematical value to determine
whether a number is an integer, and not the type alone. Therefore, there is some disagreement between validators
on this point. For example, a JavaScript-based validator may accept 1.0 as an integer, whereas the Python-based
jsonschema does not.
Clever use of the multipleOf keyword (see Multiples (page 23)) can be used to get around this discrepancy. For
example, the following likely has the same behavior on all JSON Schema implementations:
{ json schema }
{ "type": "number", "multipleOf": 1.0 }
!
42
!
42.0
%
3.14156926
4.3.2 number
The number type is used for any numeric type, either integers or floating point numbers.
Python
In Python, "number" is analogous to the float type.
Ruby
In Ruby, "number" is analogous to the Float type.
{ json schema }
!
42

!
-1
Simple floating point number:

!
5.0
Exponential notation also works:

!
2.99792458e8

%
"42"
4.3.3 Multiples
Numbers can be restricted to a multiple of a given number, using the multipleOf keyword. It may be set to any positive
number.
{ json schema }
{
"type" : "number",
"multipleOf" : 10
}
!
0
!
10
!
20
Not a multiple of 10:

%
23
4.3.4 Range
Ranges of numbers are specified using a combination of the minimum and maximum keywords, (or exclusiveMinimum
and exclusiveMaximum for expressing exclusive range).
If x is the value being validated, the following must hold true:
• x ≥ minimum
• x > exclusiveMinimum
• x ≤ maximum
• x < exclusiveMaximum
While you can specify both of minimum and exclusiveMinimum or both of maximum and exclusiveMaximum, it doesn’t
really make sense to do so.
{ json schema }
{
"type": "number",
"minimum": 0,
"exclusiveMaximum": 100
}
Less than minimum:

%
-1
minimum is inclusive, so 0 is valid:

!
0
!
10
!
99
exclusiveMaximum is exclusive, so 100 is not valid:

%
100
Greater than maximum:

%
101

Draft 4
In JSON Schema Draft 4, exclusiveMinimum and exclusiveMaximum work differently. There they are boolean
values, that indicate whether minimum and maximum are exclusive of the value. For example:
• if exclusiveMinimum is false, x ≥ minimum.
• if exclusiveMinimum is true, x > minimum.
This was changed to have better keyword independence.
Here is an example using the older Draft 4 convention:
{ json schema }
{
"type": "number",
"minimum": 0,
"maximum": 100,
"exclusiveMaximum": true
}
Less than minimum:

%
-1
exclusiveMinimum was not specified, so 0 is included:

!
0
!
10
!
99
exclusiveMaximum is true, so 100 is not included:

%
100
Greater than maximum:

%
101

4.4 object
Objects are the mapping type in JSON. They map “keys” to “values”. In JSON, the “keys” must always be strings.
Each of these pairs is conventionally referred to as a “property”.
Python
In Python, "objects" are analogous to the dict type. An important difference, however, is that while Python
dictionaries may use anything hashable as a key, in JSON all the keys must be strings.
Try not to be confused by the two uses of the word "object" here: Python uses the word object to mean the
generic base class for everything, whereas in JSON it is used only to mean a mapping from string keys to values.
Ruby
In Ruby, "objects" are analogous to the Hash type. An important difference, however, is that all keys in JSON
must be strings, and therefore any non-string keys are converted over to their string representation.
Try not to be confused by the two uses of the word "object" here: Ruby uses the word Object to mean the generic
base class for everything, whereas in JSON it is used only to mean a mapping from string keys to values.
{ json schema }
{ "type": "object" }
!
{
"key" : "value",
"another_key" : "another_value"
}
!
{
"Sun" : 1.9891e30,
"Jupiter" : 1.8986e27,
"Saturn" : 5.6846e26,
"Neptune" : 10.243e25,
"Uranus" : 8.6810e25,
"Earth" : 5.9736e24,
"Venus" : 4.8685e24,
"Mars" : 6.4185e23,
"Mercury" : 3.3022e23,
"Moon" : 7.349e22,
"Pluto" : 1.25e22
}
Using non-strings as keys is invalid JSON:
4.4. object 27
%
{
0.01 : "cm"
1 : "m",
1000 : "km"
}
%
"Not an object"
%
["An", "array", "not", "an", "object"]
4.4.1 Properties
The properties (key-value pairs) on an object are defined using the properties keyword. The value of properties is
an object, where each key is the name of a property and each value is a JSON schema used to validate that property.
For example, let’s say we want to define a simple schema for an address made up of a number, street name and street
type:
{ json schema }
{
"type": "object",
"properties": {
"number": { "type": "number" },
"street_name": { "type": "string" },
"street_type": { "type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
}
}
}
!
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue" }
If we provide the number in the wrong type, it is invalid:

%
{ "number": "1600", "street_name": "Pennsylvania", "street_type": "Avenue" }
By default, leaving out properties is valid. See Required Properties (page 30).

!
{ "number": 1600, "street_name": "Pennsylvania" }
By extension, even an empty object is valid:

!
{ }
By default, providing additional properties is valid:

!
{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue",
"direction": "NW" }
The additionalProperties keyword is used to control the handling of extra stuff, that is, properties whose names are
not listed in the properties keyword. By default any additional properties are allowed.
The additionalProperties keyword may be either a boolean or an object. If additionalProperties is a boolean
and set to false, no additional properties will be allowed.
Reusing the example above, but this time setting additionalProperties to false.
{ json schema }
{
"type": "object",
"properties": {
}
},
"additionalProperties": false
}
!
Since additionalProperties is false, this extra property “direction” makes the object invalid:
%
"direction": "NW" }
If additionalProperties is an object, that object is a schema that will be used to validate any additional properties
not listed in properties.
4.4. object 29
For example, one can allow additional properties, but only if they are each a string:
{ json schema }
{
"type": "object",
"properties": {
}
},
"additionalProperties": { "type": "string" }
}
!
This is valid, since the additional property’s value is a string:

!
"direction": "NW" }
This is invalid, since the additional property’s value is not a string:

%
"office_number": 201 }
4.4.2 Required Properties

By default, the properties defined by the properties keyword are not required. However, one can provide a list of
required properties using the required keyword.
The required keyword takes an array of zero or more strings. Each of these strings must be unique.
Draft 4
In Draft 4, required must contain at least one string.
In the following example schema defining a user record, we require that each user has a name and e-mail address, but
we don’t mind if they don’t provide their address or telephone number:

{ json schema }
{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"address": { "type": "string" },
"telephone": { "type": "string" }
},
"required": ["name", "email"]
}
!
{
"name": "William Shakespeare",
"email": "[email protected]"
}
Providing extra properties is fine, even properties not defined in the schema:
!
{
"email": "[email protected]",
"address": "Henley Street, Stratford-upon-Avon, Warwickshire, England",
"authorship": "in question"
}
Missing the required “email” property makes the JSON document invalid:
%
{
"address": "Henley Street, Stratford-upon-Avon, Warwickshire, England",
}
4.4.3 Property names

New in draft 6
The names of properties can be validated against a schema, irrespective of their values. This can be useful if you don’t
want to enforce specific properties, but you want to make sure that the names of those properties follow a specific
convention. You might, for example, want to enforce that all names are valid ASCII tokens so they can be used as
attributes in a particular programming language.
4.4. object 31
{ json schema }
{
"type": "object",
"propertyNames": {
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
}
}
!
{
"_a_proper_token_001": "value"
}
%
{
"001 invalid": "value"
}
Since object keys must always be strings anyway, so it is implied that the schema given to propertyNames is always at
least:
4.4.4 Size
The number of properties on an object can be restricted using the minProperties and maxProperties keywords. Each
of these must be a non-negative integer.
{ json schema }
{
"type": "object",
"minProperties": 2,
"maxProperties": 3
}
%
{}
%
{ "a": 0 }

!
{ "a": 0, "b": 1 }
!
{ "a": 0, "b": 1, "c": 2 }
%
{ "a": 0, "b": 1, "c": 2, "d": 3 }
4.4.5 Dependencies
Note: This is an advanced feature of JSON Schema. Windy road ahead.
The dependencies keyword allows the schema of the object to change based on the presence of certain special
properties.
There are two forms of dependencies in JSON Schema:
• Property dependencies declare that certain other properties must be present if a given property is present.
• Schema dependencies declare that the schema changes when a given property is present.
Property dependencies
Let’s start with the simpler case of property dependencies. For example, suppose we have a schema representing a
customer. If you have their credit card number, you also want to ensure you have a billing address. If you don’t have
their credit card number, a billing address would not be required. We represent this dependency of one property on
another using the dependencies keyword. The value of the dependencies keyword is an object. Each entry in the
object maps from the name of a property, p, to an array of strings listing properties that are required whenever p is
present.
In the following example, whenever a credit_card property is provided, a billing_address property must also be
present:
4.4. object 33
{ json schema }
{
"type": "object",
"properties": {
"credit_card": { "type": "number" },
"billing_address": { "type": "string" }
},
"required": ["name"],
"dependencies": {
"credit_card": ["billing_address"]
}
}
!
{
"name": "John Doe",
"credit_card": 5555555555555555,
"billing_address": "555 Debtor's Lane"
}
This instance has a credit_card, but it’s missing a billing_address.

%
{
"name": "John Doe",
"credit_card": 5555555555555555
}
This is okay, since we have neither a credit_card, or a billing_address.

!
{
"name": "John Doe"
}
Note that dependencies are not bidirectional. It’s okay to have a billing address without a credit card number.
!
{
"name": "John Doe",
}
To fix the last issue above (that dependencies are not bidirectional), you can, of course, define the bidirectional

dependencies explicitly:
{ json schema }
{
"type": "object",
"properties": {
"credit_card": { "type": "number" },
},
"dependencies": {
"credit_card": ["billing_address"],
"billing_address": ["credit_card"]
}
}
This instance has a credit_card, but it’s missing a billing_address.

%
{
"name": "John Doe",
"credit_card": 5555555555555555
}
This has a billing_address, but is missing a credit_card.

%
{
"name": "John Doe",
}
Schema dependencies
Schema dependencies work like property dependencies, but instead of just specifying other required properties, they
can extend the schema to have other constraints.
For example, here is another way to write the above:
4.4. object 35
{ json schema }
{
"type": "object",
"properties": {
"credit_card": { "type": "number" }
},
"dependencies": {
"credit_card": {
"properties": {
},
"required": ["billing_address"]
}
}
}
!
{
"name": "John Doe",
"credit_card": 5555555555555555,
}
This instance has a credit_card, but it’s missing a billing_address:

%
{
"name": "John Doe",
"credit_card": 5555555555555555
}
This has a billing_address, but is missing a credit_card. This passes, because here billing_address just looks
like an additional property:
!
{
"name": "John Doe",
}
4.4.6 Pattern Properties

As we saw above, additionalProperties can restrict the object so that it either has no additional properties that
weren’t explicitly listed, or it can specify a schema for any additional properties on the object. Sometimes that isn’t

enough, and you may want to restrict the names of the extra properties, or you may want to say that, given a particular
kind of name, the value should match a particular schema. That’s where patternProperties comes in: it is a new
keyword that maps from regular expressions to schemas. If an additional property matches a given regular expression, it
must also validate against the corresponding schema.
Note: When defining the regular expressions, it’s important to note that the expression may match anywhere within the
property name. For example, the regular expression "p" will match any property name with a p in it, such as "apple",
not just a property whose name is simply "p". It’s therefore usually less confusing to surround the regular expression in
^...$, for example, "^p$".
In this example, any additional properties whose names start with the prefix S_ must be strings, and any with the prefix
I_ must be integers. Any properties explicitly defined in the properties keyword are also accepted, and any additional
properties that do not match either regular expression are forbidden.
{ json schema }
{
"type": "object",
"patternProperties": {
"^S_": { "type": "string" },
"Î_": { "type": "integer" }
},
}
!
{ "S_25": "This is a string" }
!
{ "I_0": 42 }
If the name starts with S_, it must be a string

%
{ "S_0": 42 }
If the name starts with I_, it must be an integer

%
{ "I_42": "This is a string" }
This is a key that doesn’t match any of the regular expressions:
4.4. object 37
%
{ "keyword": "value" }
patternProperties can be used in conjunction with additionalProperties. In that case, additionalProperties

will refer to any properties that are not explicitly listed in properties and don’t match any of the patternProperties.
In the following example, based on above, we add a "builtin" property, which must be a number, and declare that all
additional properties (that are neither built-in or matched by patternProperties) must be strings:
{ json schema }
{
"type": "object",
"properties": {
"builtin": { "type": "number" }
},
"patternProperties": {
"^S_": { "type": "string" },
"Î_": { "type": "integer" }
},
"additionalProperties": { "type": "string" }
}
!
{ "builtin": 42 }
This is a key that doesn’t match any of the regular expressions:

!
{ "keyword": "value" }
It must be a string:
%
{ "keyword": 42 }
4.5 array
Arrays are used for ordered elements. In JSON, each element in an array may be of a different type.
Python
In Python, "array" is analogous to a list or tuple type, depending on usage. However, the json module in the
Python standard library will always use Python lists to represent JSON arrays.

Ruby
In Ruby, "array" is analogous to a Array type.
{ json schema }
{ "type": "array" }
!
[1, 2, 3, 4, 5]
!
[3, "different", { "types" : "of values" }]
%
{"Not": "an array"}
4.5.1 Items
By default, the elements of the array may be anything at all. However, it’s often useful to validate the items of the array
against some schema as well. This is done using the items, additionalItems, and contains keywords.
There are two ways in which arrays are generally used in JSON:
• List validation: a sequence of arbitrary length where each item matches the same schema.
• Tuple validation: a sequence of fixed length where each item may have a different schema. In this usage, the
index (or location) of each item is meaningful as to how the value is interpreted. (This usage is often given a
whole separate type in some programming languages, such as Python’s tuple).
List validation
List validation is useful for arrays of arbitrary length where each item matches the same schema. For this kind of array,
set the items keyword to a single schema that will be used to validate all of the items in the array.
Note: When items is a single schema, the additionalItems keyword is meaningless, and it should not be used.
In the following example, we define that each item in an array is a number:
4.5. array 39
{ json schema }
{
"type": "array",
"items": {
"type": "number"
}
}
!
[1, 2, 3, 4, 5]
A single “non-number” causes the whole array to be invalid:

%
[1, 2, "3", 4, 5]
The empty array is always valid:

!
[]
New in draft 6
While the items schema must be valid for every item in the array, the contains schema only needs to validate against
one or more items in the array.
{ json schema }
{
"type": "array",
"contains": {
"type": "number"
}
}
A single “number” is enough to make this pass:

!
["life", "universe", "everything", 42]
But if we have no number, it fails:

%
["life", "universe", "everything", "forty-two"]

All numbers is, of course, also okay:

!
[1, 2, 3, 4, 5]
Tuple validation
Tuple validation is useful when the array is a collection of items where each has a different schema and the ordinal
index of each item is meaningful.
For example, you may represent a street address such as:
1600 Pennsylvania Avenue NW
as a 4-tuple of the form:

[number, street_name, street_type, direction]
Each of these fields will have a different schema:
• number: The address number. Must be a number.
• street_name: The name of the street. Must be a string.
• street_type: The type of street. Should be a string from a fixed set of values.
• direction: The city quadrant of the address. Should be a string from a different set of values.
To do this, we set the items keyword to an array, where each item is a schema that corresponds to each index of the
document’s array. That is, an array where the first element validates the first element of the input array, the second
element validates the second element of the input array, etc.
Here’s the example schema:
{ json schema }
{
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "string",
},
{
"type": "string",
"enum": ["NW", "NE", "SW", "SE"]
}
]
}
4.5. array 41
!
[1600, "Pennsylvania", "Avenue", "NW"]
“Drive” is not one of the acceptable street types:

%
[24, "Sussex", "Drive"]
This address is missing a street number

%
["Palais de l'Élysée"]
It’s okay to not provide all of the items:

!
[10, "Downing", "Street"]
And, by default, it’s also okay to add additional items to end:

!
[1600, "Pennsylvania", "Avenue", "NW", "Washington"]
The additionalItems keyword controls whether it’s valid to have additional items in the array beyond what is defined
in items. Here, we’ll reuse the example schema above, but set additionalItems to false, which has the effect of
disallowing extra items in the array.

{ json schema }
{
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "string",
},
{
"type": "string",
"enum": ["NW", "NE", "SW", "SE"]
}
],
"additionalItems": false
}
!
[1600, "Pennsylvania", "Avenue", "NW"]
It’s ok to not provide all of the items:

!
[1600, "Pennsylvania", "Avenue"]
But, since additionalItems is false, we can’t provide extra items:

%
The additionalItems keyword may also be a schema to validate against every additional item in the array. In that
case, we could say that additional items are allowed, as long as they are all strings:
4.5. array 43
{ json schema }
{
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "string",
},
{
"type": "string",
"enum": ["NW", "NE", "SW", "SE"]
}
],
"additionalItems": { "type": "string" }
}
Extra string items are ok. . .

!
..but not anything else

%
[1600, "Pennsylvania", "Avenue", "NW", 20500]
Note: additionalItems doesn’t make sense if you’re doing “list validation” (items is an object), and is ignored in
the case.
4.5.2 Length
The length of the array can be specified using the minItems and maxItems keywords. The value of each keyword must
be a non-negative number. These keywords work whether doing List validation (page 39) or Tuple validation (page 41).
{ json schema }
{
"type": "array",
"minItems": 2,
"maxItems": 3
}

%
[]
%
[1]
!
[1, 2]
!
[1, 2, 3]
%
[1, 2, 3, 4]
4.5.3 Uniqueness
A schema can ensure that each of the items in an array is unique. Simply set the uniqueItems keyword to true.
{ json schema }
{
"type": "array",
"uniqueItems": true
}
!
[1, 2, 3, 4, 5]
%
[1, 2, 3, 3, 4]
The empty array always passes:

!
[]
4.5. array 45
4.6 boolean
The boolean type matches only two special values: true and false. Note that values that evaluate to true or false,
such as 1 and 0, are not accepted by the schema.
Python
In Python, "boolean" is analogous to bool. Note that in JSON, true and false are lower case, whereas in Python
they are capitalized (True and False).
Ruby
In Ruby, "boolean" is analogous to TrueClass and FalseClass. Note that in Ruby there is no Boolean class.
{ json schema }
{ "type": "boolean" }
!
true
!
false
%
"true"
Values that evaluate to true or false are still not accepted by the schema:
%
0
4.7 null
The null type is generally used to represent a missing value. When a schema specifies a type of null, it has only one
acceptable value: null.
Python
In Python, null is analogous to None.

Ruby
In Ruby, null is analogous to nil.
{ json schema }
{ "type": "null" }
!
null
%
false
%
0
%
""
4.8 Generic keywords

This chapter lists some miscellaneous properties that are available for all JSON types.
4.8.1 Metadata
JSON Schema includes a few keywords, title, description, default, and examples that aren’t strictly used for
validation, but are used to describe parts of a schema.
The title and description keywords must be strings. A “title” will preferably be short, whereas a “description” will
provide a more lengthy explanation about the purpose of the data described by the schema. Neither are required, but
they are encouraged for good practice, and can make your schema “self-documenting”.
The default keyword specifies a default value for an item. JSON processing tools may use this information to provide
a default value for a missing key/value pair, though many JSON schema validators simply ignore the default keyword.
It should validate against the schema in which it resides, but that isn’t required.
New in draft 6 The examples keyword is a place to provide an array of examples that validate against the schema. This
isn’t used for validation, but may help with explaining the effect and purpose of the schema to a reader. Each entry
should validate against the schema in which is resides, but that isn’t strictly required. There is no need to duplicate the
default value in the examples array, since default will be treated as another example.
4.8. Generic keywords 47

{ json schema }
{
"title" : "Match anything",
"description" : "This is a schema that matches anything.",
"default" : "Default value",
"examples" : [
"Anything",
4035
]
}
4.8.2 Enumerated values

The enum keyword is used to restrict a value to a fixed set of values. It must be an array with at least one element, where
each element is unique.
The following is an example for validating street light colors:
{ json schema }
{
"type": "string",
"enum": ["red", "amber", "green"]
}
!
"red"
%
"blue"
You can use enum even without a type, to accept values of different types. Let’s extend the example to use null to
indicate “off”, and also add 42, just for fun.
{ json schema }
{
"enum": ["red", "amber", "green", null, 42]
}
!
"red"

!
null
!
42
%
0
However, in most cases, the elements in the enum array should also be valid against the enclosing schema:
{ json schema }
{
"type": "string",
"enum": ["red", "amber", "green", null]
}
!
"red"
This is in the enum, but it’s invalid against { "type": "string" }, so it’s ultimately invalid:
%
null
4.8.3 Constant values

New in draft 6
The const keyword is used to restrict a value to a single value.
For example, to if you only support shipping to the United States for export reasons:
{ json schema }
{
"properties": {
"country": {
"const": "United States of America"
}
}
}
4.8. Generic keywords 49

!
{ "country": "United States of America" }
%
{ "country": "Canada" }
It should be noted that const is merely syntactic sugar for an enum with a single element, therefore the following are
equivalent:
{ "const": "United States of America" }
{ "enum": [ "United States of America" ] }
4.9 Combining schemas

JSON Schema includes a few keywords for combining schemas together. Note that this doesn’t necessarily mean
combining schemas from multiple files or JSON trees, though these facilities help to enable that and are described in
Structuring a complex schema (page 59). Combining schemas may be as simple as allowing a value to be validated
against multiple criteria at the same time.
For example, in the following schema, the anyOf keyword is used to say that the given value may be valid against any
of the given subschemas. The first subschema requires a string with maximum length 5. The second subschema requires
a number with a minimum value of 0. As long as a value validates against either of these schemas, it is considered valid
against the entire combined schema.
{ json schema }
{
"anyOf": [
{ "type": "string", "maxLength": 5 },
{ "type": "number", "minimum": 0 }
]
}
!
"short"
%
"too long"
!
12

%
-5
The keywords used to combine schemas are:

• allOf (page 51): Must be valid against all of the subschemas
• anyOf (page 53): Must be valid against any of the subschemas
• oneOf (page 54): Must be valid against exactly one of the subschemas
All of these keywords must be set to an array, where each item is a schema.
In addition, there is:
• not (page 55): Must not be valid against the given schema
4.9.1 allOf
To validate against allOf, the given data must be valid against all of the given subschemas.
{ json schema }
{
"allOf": [
{ "type": "string" },
{ "maxLength": 5 }
]
}
!
"short"
%
"too long"
Note that it’s quite easy to create schemas that are logical impossibilities with allOf. The following example creates a
schema that won’t validate against anything (since something may not be both a string and a number at the same time):
{ json schema }
{
"allOf": [
]
}
4.9. Combining schemas 51

%
"No way"
%
-1
It is important to note that the schemas listed in an allOf (page 51), anyOf (page 53) or oneOf (page 54) array know
nothing of one another. While it might be surprising, allOf (page 51) can not be used to “extend” a schema to add
more details to it in the sense of object-oriented inheritance. For example, say you had a schema for an address in a
definitions section, and want to extend it to include an address type:
{ json schema }
{
"definitions": {
"address": {
"type": "object",
"properties": {
"state": { "type": "string" }
},
"required": ["street_address", "city", "state"]
}
},
"allOf": [
{ "$ref": "#/definitions/address" },
{ "properties": {
"type": { "enum": [ "residential", "business" ] }
}
}
]
}
!
{
"street_address": "1600 Pennsylvania Avenue NW",
"city": "Washington",
"state": "DC",
"type": "business"
}
This works, but what if we wanted to restrict the schema so no additional properties are allowed? One might try adding
the highlighted line below:

{ json schema }
{
"definitions": {
"address": {
"type": "object",
"properties": {
},
}
},
"allOf": [
{ "properties": {
}
}
],
}
%
{
"state": "DC",
"type": "business"
}
Unfortunately, now the schema will reject everything. This is because the Properties (page 28) refers to the entire
schema. And that entire schema includes no properties, and knows nothing about the properties in the subschemas
inside of the allOf (page 51) array.
This shortcoming is perhaps one of the biggest surprises of the combining operations in JSON schema: it does not
behave like inheritance in an object-oriented language. There are some proposals to address this in the next version of
the JSON schema specification.
4.9.2 anyOf
To validate against anyOf, the given data must be valid against any (one or more) of the given subschemas.
4.9. Combining schemas 53

{ json schema }
{
"anyOf": [
]
}
!
"Yes"
!
42
%
{ "Not a": "string or number" }
4.9.3 oneOf
To validate against oneOf, the given data must be valid against exactly one of the given subschemas.
{ json schema }
{
"oneOf": [
{ "type": "number", "multipleOf": 5 },
{ "type": "number", "multipleOf": 3 }
]
}
!
10
!
9
Not a multiple of either 5 or 3.

%
2

Multiple of both 5 and 3 is rejected.

%
15
Note that it’s possible to “factor” out the common parts of the subschemas. The following schema is equivalent to the
one above:
{ json schema }
{
"type": "number",
"oneOf": [
{ "multipleOf": 5 },
{ "multipleOf": 3 }
]
}
4.9.4 not
This doesn’t strictly combine schemas, but it belongs in this chapter along with other things that help to modify the
effect of schemas in some way. The not keyword declares that a instance validates if it doesn’t validate against the
given subschema.
For example, the following schema validates against anything that is not a string:
{ json schema }
{ "not": { "type": "string" } }
!
42
!
{ "key": "value" }
%
"I am a string"
4.10 The $schema keyword

The $schema keyword is used to declare that a JSON fragment is actually a piece of JSON Schema. It also declares
which version of the JSON Schema standard that the schema was written against.
4.10. The $schema keyword 55

It is recommended that all JSON Schemas have a $schema entry, which must be at the root. Therefore most of the time,
you’ll want this at the root of your schema:
"$schema": "http://json-schema.org/schema#"
4.10.1 Advanced
If you need to declare that your schema was written against a specific version of the JSON Schema standard, you should
include the draft name in the path, for example:
• http://json-schema.org/draft-06/schema#
• http://json-schema.org/draft-04/schema#
Additionally, if you have extended the JSON Schema language to include your own custom keywords for validating
values, you can use a custom URI for $schema. It must not be one of the predefined values above, and should probably
include a domain name you own.
4.11 Regular Expressions

The pattern (page 19) and Pattern Properties (page 36) keywords use regular expressions to express constraints. The
regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that complete syntax is not
widely supported, therefore it is recommended that you stick to the subset of that syntax described below.
• A single unicode character (other than the special characters below) matches itself.
• ^: Matches only at the beginning of the string.
• $: Matches only at the end of the string.
• (...): Group a series of regular expressions into a single regular expression.
• |: Matches either the regular expression preceding or following the | symbol.
• [abc]: Matches any of the characters inside the square brackets.
• [a-z]: Matches the range of characters.
• [âbc]: Matches any character not listed.
• [â-z]: Matches any character outside of the range.
• +: Matches one or more repetitions of the preceding regular expression.
• *: Matches zero or more repetitions of the preceding regular expression.
• ?: Matches zero or one repetitions of the preceding regular expression.
• +?, *?, ??: The *, +, and ? qualifiers are all greedy; they match as much text as possible. Sometimes this behavior
isn’t desired and you want to match as few characters as possible.
• (?!x}, (?=x}: Negative and positive lookahead.
• {x}: Match exactly x occurrences of the preceding regular expression.
• {x,y}: Match at least x and at most y occurrences of the preceding regular expression.
• {x,}: Match x occurrences or more of the preceding regular expression.
• {x}?, {x,y}?, {x,}?: Lazy versions of the above expressions.

Python
This subset of JavaScript regular expressions is compatible with Python regular expressions. Pay close attention
to what is missing, however. Notably, it is not recommended to use . to match any character.
4.11.1 Example
The following example matches a simple North American telephone number with an optional area code:
{ json schema }
{
"type": "string",
"pattern": "^(\$[0-9]{3}\$)?[0-9]{3}-[0-9]{4}$"
}
!
"555-1212"
!
"(888)555-1212"
%
"(888)555-1212 ext. 532"
%
"(800)FLOWERS"
4.11. Regular Expressions 57


CHAPTER 5
Structuring a complex schema
When writing computer programs of even moderate complexity, it’s commonly accepted that “structuring” the program
into reusable functions is better than copying-and-pasting duplicate bits of code everywhere they are used. Likewise in
JSON Schema, for anything but the most trivial schema, it’s really useful to structure the schema into parts that can be
reused in a number of places. This chapter will present some practical examples that use the tools available for reusing
and structuring schemas.
5.1 Reuse
For this example, let’s say we want to define a customer record, where each customer may have both a shipping and
a billing address. Addresses are always the same—they have a street address, city and state—so we don’t want to
duplicate that part of the schema everywhere we want to store an address. Not only would that make the schema more
verbose, but it makes updating it in the future more difficult. If our imaginary company were to start doing international
business in the future and we wanted to add a country field to all the addresses, it would be better to do this in a single
place rather than everywhere that addresses are used.
So let’s start with the schema that defines an address:
{
"type": "object",
"properties": {
},
}
Since we are going to reuse this schema, it is customary (but not required) to put it in the parent schema under a key
called definitions:
{
"definitions": {
"address": {
59

"type": "object",
"properties": {
},
}
}
}
We can then refer to this schema snippet from elsewhere using the $ref keyword. The easiest way to describe $ref is
that it gets logically replaced with the thing that it points to. So, to refer to the above, we would include:
{ "$ref": "#/definitions/address" }
This can be used anywhere a schema is expected. You will always use $ref as the only key in an object: any other keys
you put there will be ignored by the validator.
The value of $ref is a URI, and the part after # sign (the “fragment” or “named anchor”) is in a format called JSON
Pointer.
Note: JSON Pointer aims to serve the same purpose as XPath from the XML world, but it is much simpler.
If you’re using a definition from the same document, the $ref value begins with the pound symbol (#). Following that,
the slash-separated items traverse the keys in the objects in the document. Therefore, in our example "#/definitions/
address" means:
1) go to the root of the document
2) find the value of the key "definitions"
3) within that object, find the value of the key "address"
$ref can also be a relative or absolute URI, so if you prefer to include your definitions in separate files, you can also do
that. For example:
{ "$ref": "definitions.json#/address" }
would load the address schema from another file residing alongside this one.
Now let’s put this together and use our address schema to create a schema for a customer:
60 Chapter 5. Structuring a complex schema

{ json schema }
{
"$schema": "http://json-schema.org/draft-06/schema#",
"definitions": {
"address": {
"type": "object",
"properties": {
},
}
},
"type": "object",
"properties": {
"billing_address": { "$ref": "#/definitions/address" },
"shipping_address": { "$ref": "#/definitions/address" }
}
}
!
{
"shipping_address": {
"state": "DC"
},
"billing_address": {
"street_address": "1st Street SE",
"state": "DC"
}
}
Note: Even though the value of a $ref is a URI, it is not a network locator, only an identifier. This means that the
schema doesn’t need to be accessible at that URI, but it may be. It is basically up to the validator implementation how
external schema URIs will be handled, but one should not assume the validator will fetch network resources indicated
in $ref values.
5.1.1 Recursion
$ref elements may be used to create recursive schemas that refer to themselves. For example, you might have a person
schema that has an array of children, each of which are also person instances.
5.1. Reuse 61
{ json schema }
{
"definitions": {
"person": {
"type": "object",
"properties": {
"children": {
"type": "array",
"items": { "$ref": "#/definitions/person" },
"default": []
}
}
}
},
"type": "object",
"properties": {
"person": { "$ref": "#/definitions/person" }
}
}
A snippet of the British royal family tree

!
{
"person": {
"name": "Elizabeth",
"children": [
{
"name": "Charles",
"children": [
{
"name": "William",
"children": [
{ "name": "George" },
{ "name": "Charlotte" }
]
},
{
"name": "Harry"
}
]
}
]
}
}
Above, we created a schema that refers to another part of itself, effectively creating a “loop” in the validator, which is
both allowed and useful. Note, however, that a loop of $ref schemas referring to one another could cause an infinite
loop in the resolver, and is explicitly disallowed.

{ json schema }
{
"definitions": {
"alice": {
"anyOf": [
{ "$ref": "#/definitions/bob" }
]
},
"bob": {
"anyOf": [
{ "$ref": "#/definitions/alice" }
]
}
}
}
5.2 The $id property

The $id property is a URI that serves two purposes:
• It declares a unique identifier for the schema.
• It declares a base URI against which $ref URIs are resolved.
It is best practice that every top-level schema should set $id to an absolute URI, with a domain that you control. For
example, if you own the foo.bar domain, and you had a schema for addresses, you may set its $id as follows:
{ json schema }
{ "$id": "http://foo.bar/schemas/address.json" }
This provides a unique identifier for the schema, as well as, in most cases, indicating where it may be downloaded.
But be aware of the second purpose of the $id property: that it declares a base URL for relative $ref URLs elsewhere
in the file. For example, if you had:
{ json schema }
{ "$ref": "person.json" }
in the same file, a JSON schema validation library that supported network fetching would fetch person.json from
http://foo.bar/schemas/person.json, even if address.json was loaded from somewhere else, such as the local
filesystem.
New in draft 6
Draft 4
In Draft 4, $id is just id (without the dollar sign).
The $id property should never be the empty string or an empty fragment (#), since that doesn’t really make sense.
5.2. The $id property 63

5.2.1 Using $id with $ref

$id also provides a way to refer to subschema without using JSON Pointer. This means you can refer to them by a
unique name, rather than by where they appear in the JSON tree.
Reusing the address example above, we can add an $id property to the address schema, and refer to it by that instead.
{ json schema }
{
"definitions": {
"address": {
"$id": "#address",
"type": "object",
"properties": {
},
}
},
"type": "object",
"properties": {
"billing_address": { "$ref": "#address" },
"shipping_address": { "$ref": "#address" }
}
}
Note: This functionality isn’t currently supported by the Python jsonschema library.
5.3 Extending
The power of $ref really shines when it is used with the combining keywords allOf, anyOf and oneOf (see Combining
schemas (page 50)).
Let’s say that for a shipping address, we want to know whether the address is a residential or business address, because
the shipping method used may depend on that. For a billing address, we don’t want to store that information, because
it’s not applicable.
To handle this, we’ll update our definition of shipping address:
"shipping_address": { "$ref": "#/definitions/address" }
to instead use an allOf keyword entry combining both the core address schema definition and an extra schema snippet
for the address type:
"allOf": [


// Here, we include our "core" address schema...
// ...and then extend it with stuff specific to a shipping

// address
{ "properties": {
},
"required": ["type"]
}
]
}
Tying this all together,
{ json schema }
{
"definitions": {
"address": {
"type": "object",
"properties": {
},
}
},
"type": "object",
"properties": {
"billing_address": { "$ref": "#/definitions/address" },
"allOf": [
{ "properties":
{ "type": { "enum": [ "residential", "business" ] } },
"required": ["type"]
}
]
}
}
}
This fails, because it’s missing an address type:
5.3. Extending 65
%
{
"state": "DC"
}
}
!
{
"state": "DC",
"type": "business"
}
}
From these basic pieces, it’s possible to build very powerful constructions without a lot of duplication.

CHAPTER 6
Acknowledgments
Michael Droettboom wishes to thank the following contributors:

• Alexander Kjeldaas
• Anders D. Johnson
• Armand Abric
• Ben Hutton
• Brandon Wright
• btubbs
• Chris Carpenter
• Christopher Mark Gore
• David Branner
• David Michael Karr
• David Worth
• E. M. Bray
• Fenhl
• forevermatt
• goldaxe
• Jesse Claven
• Koen Rouwhorst
• Mike Kobit
• Oliver Kurmis
• Vincent Jacques
67
68 Chapter 6. Acknowledgments
Index
Symbols examples, 47
$id, 63 exclusiveMaximum, 24
$ref, 60 exclusiveMinimum, 24
$schema, 55
F
A format, 20
additionalItems, 39
additionalProperties, 28
H
allOf, 51 hostname, 20
anyOf, 53
array, 38
I
items, 39 integer, 20
length, 44 ipv4, 20
list validation, 39 ipv6, 20
tuple validation, 41 items, 39
uniqueness, 45
J
B json-pointer, 20
boolean, 45 M
C maximum, 24
maxItems, 44
combining schemas, 50
maxLength, 18
allOf, 51
maxProperties, 32
anyOf, 53
metadata, 47
not, 55
minimum, 24
oneOf, 54
minItems, 44
const, 49
minLength, 18
constant values, 49
minProperties, 32
contains, 39
multipleOf, 23
D N
date-time, 20
not, 55
dependencies, 33
null, 46
description, 47
number, 20, 22
E multiple of, 23
range, 24
email, 20
enum, 48 O
enumerated values, 48
object, 27
69
dependencies, 33
properties, 28
property names, 31
regular expression, 36
required properties, 30
size, 32
oneOf, 54
P
pattern, 19
patternProperties, 36
properties, 28
propertyNames, 31
R
regular expressions, 56
required, 30
S
schema
keyword, 55
string, 17
format, 20
length, 18
regular expression, 19
structure, 57
T
title, 47
type, 15
types
basic, 15
numeric, 20
U
uniqueItems, 45
uri, 20
uri-reference, 20
uri-template, 20
70 Index

Understanding JSONSchema

Uploaded by

Copyright:

Available Formats

Understanding JSONSchema

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Understanding JSONSchema

Uploaded by

Copyright:

Available Formats

Understanding JSON Schema

Nov 09, 2018

1 Conventions used in this book 3

4 JSON Schema Reference 15

5 Structuring a complex schema 59

Conventions used in this book

1.1 Language-specific notes

In Ruby, JSON can be read using the json gem.

1.2 Draft-specific notes

which an earlier version of this book was written.

This is where anything pertaining to an old draft would be mentioned.

Simple floating point number:

Exponential notation also works:

Numbers as strings are rejected:

4 Chapter 1. Conventions used in this book

6 Chapter 1. Conventions used in this book

{ "key1": "value1", "key2": "value2" }

[ "first", "second", "third" ]

8 Chapter 2. What is a schema?

(continued from previous page)

However, the second example passes:

10 Chapter 2. What is a schema?

3.1 Hello, World!

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

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

3.2 The type keyword

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

12 Chapter 3. The basics

3.3 Declaring a JSON Schema

3.4 Declaring a unique identifier

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

3.3. Declaring a JSON Schema 13

14 Chapter 3. The basics

JSON Schema Reference

4.1 Type-specific keywords

The type keyword may either be a string or an array:

16 Chapter 4. JSON Schema Reference

This is not a number, it is a string containing a number.

{ "type": ["number", "string"] }

In Ruby, "string" is analogous to the String type.

18 Chapter 4. JSON Schema Reference

4.2.2 Regular Expressions

URI vs. URI reference

20 Chapter 4. JSON Schema Reference

4.3 Numeric types

In Python, "integer" is analogous to the int type.

In Ruby, "integer" is analogous to the Integer type.

Floating point numbers are rejected:

Numbers as strings are rejected:

4.3. Numeric types 21

{ "type": "number", "multipleOf": 1.0 }

In Python, "number" is analogous to the float type.

In Ruby, "number" is analogous to the Float type.

22 Chapter 4. JSON Schema Reference

Simple floating point number:

Exponential notation also works:

Numbers as strings are rejected:

Not a multiple of 10:

4.3. Numeric types 23