The latest Internet-Drafts at the IETF are the draft-wright-json-schema*-01 - documents, which correspond to the draft-06 meta-schemas. These were - published on 2017-04-15. - (Due to a change in authorship the I-D numbering was reset with the previous draft). - The specification is split into three parts, Core, Validation, and Hyper-Schema:
They are also available on the IETF main site: core (draft-wright-json-schema-01), validation (draft-wright-json-schema-validation-01) and hyper-schema (draft-wright-json-schema-hyperschema-01). -
For previous versions of the specification, please see the Specification Links page on our github wiki. -
The meta-schemas are the schemas which define the JSON Schema and Hyper-Schema formats.
The latest meta-schema is draft-06.
These sample schemas describe simple data structures which can be expressed as JSON: -
Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an id, a name, a price, and an optional set of tags.
An example product in this API is:
+### Example JSON data for a product API + +An example product in this API is: + +```json { "id": 1, "name": "A green door", "price": 12.50, "tags": ["home", "green"] } -
While generally straightforward, that example leaves some open questions. For example, one may ask:
When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.
To start a schema definition, let's begin with a basic JSON schema:
+To start a schema definition, let's begin with a basic JSON schema: + +```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", "description": "A product from Acme's catalog", "type": "object" } -
The above schema has four properties called keywords. +The *type* keyword defines the first constraint on our JSON data: it has to be a JSON Object. - The title and description keywords are descriptive only, in that they do not add - constraints to the data being validated. The intent of the schema is stated with these two keywords - (that is, this schema describes a product).
The type keyword defines the first constraint on our JSON data: it has to be a JSON - Object.
Finally, the $schema keyword states that this schema is written according to the draft - v4 specification.
Next let's answer our previous questions about this API, starting with id.
id is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required.
In JSON Schema terms, we can update our schema to:
+In JSON Schema terms, we can update our schema to: + +```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", @@ -78,13 +74,13 @@ What is id? }, "required": ["id"] } -
name is a string value that describes a product. Since there isn't - much to a product without a name, it also is required. Adding this gives us the schema:
+```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", @@ -102,12 +98,13 @@ Is name required? }, "required": ["id", "name"] } -
According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify exclusiveMinimum. Therefore we can update our schema with price:
+```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", @@ -130,25 +127,20 @@ Can price be 0? }, "required": ["id", "name", "price"] } -
Finally, we come to the tags property. Unlike the previous - properties, tags have many values, and is represented as a JSON array. According - to Acme's docs, all tags must be strings, but you aren't required to specify - tags. We simply leave tags out of the list of required properties.
However, Acme's docs add two constraints:
The first constraint can be added with minItems, and the second one by - specifying uniqueItems as being true:
+The first constraint can be added with *minItems*, and the second one by specifying *uniqueItems* as being true: + +```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", @@ -179,17 +171,20 @@ Are all tags strings? }, "required": ["id", "name", "price"] } -
The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the full standard draft.
As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a dimensions property for the size of the product, and the second is a warehouseLocation field for where the warehouse that stores them is geographically located.
And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the canonical one.
+And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the [canonical one](http://json-schema.org/geo). + +### Set of products: + +```json [ { "id": 2, @@ -221,10 +216,11 @@ Set of products: } } ] -
+```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product set", @@ -270,6 +266,5 @@ Set of products schema: "required": ["id", "name", "price"] } } -
This example shows a possible JSON representation of a hypothetical machine's mount points as - represented in an /etc/fstab file.
/etc/fstab
An entry in the fstab file can have many different forms. Here is a possible representation of a - full fstab:
-{ - "/": { - "storage": { - "type": "disk", - "device": "/dev/sda1" - }, - "fstype": "btrfs", - "readonly": true - }, - "/var": { - "storage": { - "type": "disk", - "label": "8f3ba6f4-5c70-46ec-83af-0d5434953e5f" - }, - "fstype": "ext4", - "options": [ "nosuid" ] - }, - "/tmp": { - "storage": { - "type": "tmpfs", - "sizeInMB": 64 - } - }, - "/var/www": { - "storage": { - "type": "nfs", - "server": "my.nfs.server", - "remotePath": "/exports/mypath" - } - } -} -
Not all constraints to an fstab file can be modeled using JSON Schema alone; however, it can - already represent a good number of them. We will add constraints one after the other until we get to - a satisfactory result.
We will start with a base schema expressing the following constraints:
/
We also want the schema to be regarded as a draft v4 schema, we must therefore specify - $schema:
-{ - "$schema": "http://json-schema.org/draft-04/schema#", - "type": "object", - "properties": { - "/": {} - }, - "patternProperties": { - "^(/[^/]+)+$": {} - }, - "additionalProperties": false, - "required": [ "/" ] -} -
Note how the valid paths constraint is enforced here:
You will notice that the regular expression is explicitly anchored (with ^ and - $): in JSON Schema, regular expressions (in patternProperties and in - pattern) are not anchored by default.
^
$
For now, the schemas describing individual entries are empty: we will start describing the - constraints in the following paragraphs, using another schema, which we will reference from the main - schema when we are ready.
Here again we will proceed step by step. We will start with the global structure of our schema, which will be as such:
-{ - "id": "http://some.site.somewhere/entry-schema#", - "$schema": "http://json-schema.org/draft-04/schema#", - "description": "schema for an fstab entry", - "type": "object", - "required": [ "storage" ], - "properties": { - "storage": { - "type": "object", - "oneOf": [ - { "$ref": "#/definitions/diskDevice" }, - { "$ref": "#/definitions/diskUUID" }, - { "$ref": "#/definitions/nfs" }, - { "$ref": "#/definitions/tmpfs" } - ] - } - }, - "definitions": { - "diskDevice": {}, - "diskUUID": {}, - "nfs": {}, - "tmpfs": {} - } -} -
You should already be familiar with some of the constraints:
"type": "object"
"required": [ "storage" ]
There are a couple of novelties:
Let's now extend this skeleton to add constraints to these three properties. Note that none of - them are required:
ext3
ext4
btrfs
With these added constraints, the schema now looks like this:
-{ - "id": "http://some.site.somewhere/entry-schema#", - "$schema": "http://json-schema.org/draft-04/schema#", - "description": "schema for an fstab entry", - "type": "object", - "required": [ "storage" ], - "properties": { - "storage": { - "type": "object", - "oneOf": [ - { "$ref": "#/definitions/diskDevice" }, - { "$ref": "#/definitions/diskUUID" }, - { "$ref": "#/definitions/nfs" }, - { "$ref": "#/definitions/tmpfs" } - ] - }, - "fstype": { - "enum": [ "ext3", "ext4", "btrfs" ] - }, - "options": { - "type": "array", - "minItems": 1, - "items": { "type": "string" }, - "uniqueItems": true - }, - "readonly": { "type": "boolean" } - }, - "definitions": { - "diskDevice": {}, - "diskUUID": {}, - "nfs": {}, - "tmpfs": {} - } -} -
For now, all definitions are empty (an empty JSON Schema validates all instances). We will write - schemas for individual definitions below, and fill these schemas into the entry schema.
This storage type has two required properties, type and device. The type can - only be disk, and the device must be an absolute path starting with /dev. No other - properties are allowed:
-{ - "properties": { - "type": { "enum": [ "disk" ] }, - "device": { - "type": "string", - "pattern": "^/dev/[^/]+(/[^/]+)*$" - } - }, - "required": [ "type", "device" ], - "additionalProperties": false -} -
You will have noted that we need not specify that type must be a string: the constraint - described by enum is enough.
This storage type has two required properties, type and label. The type can - only be disk, and the label must be a valid UUID. No other properties are allowed:
-{ - "properties": { - "type": { "enum": [ "disk" ] }, - "label": { - "type": "string", - "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$" - } - }, - "required": [ "type", "label" ], - "additionalProperties": false -} -
This storage type has three required properties: type, server and - remotePath. What is more, the server may be either a host name, an IPv4 address or an IPv6 - address.
For the constraints on server, we use a new keyword: format. While it is not - required that format be supported, we will suppose that it is here:
-{ - "properties": { - "type": { "enum": [ "nfs" ] }, - "remotePath": { - "type": "string", - "pattern": "^(/[^/]+)+$" - }, - "server": { - "type": "string", - "oneOf": [ - { "format": "host-name" }, - { "format": "ipv4" }, - { "format": "ipv6" } - ] - } - }, - "required": [ "type", "server", "remotePath" ], - "additionalProperties": false -} -
This storage type has two required properties: type and sizeInMB. The size can - only be an integer. What is more, we will require that the size be between 16 and 512, - inclusive:
-{ - "properties": { - "type": { "enum": [ "tmpfs" ] }, - "sizeInMB": { - "type": "integer", - "minimum": 16, - "maximum": 512 - } - }, - "required": [ "type", "sizeInMB" ], - "additionalProperties": false -} -
The resulting schema is quite large:
-{ - "id": "http://some.site.somewhere/entry-schema#", - "$schema": "http://json-schema.org/draft-04/schema#", - "description": "schema for an fstab entry", - "type": "object", - "required": [ "storage" ], - "properties": { - "storage": { - "type": "object", - "oneOf": [ - { "$ref": "#/definitions/diskDevice" }, - { "$ref": "#/definitions/diskUUID" }, - { "$ref": "#/definitions/nfs" }, - { "$ref": "#/definitions/tmpfs" } - ] - }, - "fstype": { - "enum": [ "ext3", "ext4", "btrfs" ] - }, - "options": { - "type": "array", - "minItems": 1, - "items": { "type": "string" }, - "uniqueItems": true - }, - "readonly": { "type": "boolean" } - }, - "definitions": { - "diskDevice": { - "properties": { - "type": { "enum": [ "disk" ] }, - "device": { - "type": "string", - "pattern": "^/dev/[^/]+(/[^/]+)*$" - } - }, - "required": [ "type", "device" ], - "additionalProperties": false - }, - "diskUUID": { - "properties": { - "type": { "enum": [ "disk" ] }, - "label": { - "type": "string", - "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$" - } - }, - "required": [ "type", "label" ], - "additionalProperties": false - }, - "nfs": { - "properties": { - "type": { "enum": [ "nfs" ] }, - "remotePath": { - "type": "string", - "pattern": "^(/[^/]+)+$" - }, - "server": { - "type": "string", - "oneOf": [ - { "format": "host-name" }, - { "format": "ipv4" }, - { "format": "ipv6" } - ] - } - }, - "required": [ "type", "server", "remotePath" ], - "additionalProperties": false - }, - "tmpfs": { - "properties": { - "type": { "enum": [ "tmpfs" ] }, - "sizeInMB": { - "type": "integer", - "minimum": 16, - "maximum": 512 - } - }, - "required": [ "type", "sizeInMB" ], - "additionalProperties": false - } - } -} -
Now that all possible entries have been described, we can refer to the entry schema from our main - schema. We will, again, use a JSON Reference here:
-{ - "$schema": "http://json-schema.org/draft-04/schema#", - "type": "object", - "properties": { - "/": { "$ref": "http://some.site.somewhere/entry-schema#" } - }, - "patternProperties": { - "^(/[^/]+)+$": { "$ref": "http://some.site.somewhere/entry-schema#" } - }, - "additionalProperties": false, - "required": [ "/" ] -} -
This example is much more advanced than the previous example; you will have learned of schema - referencing and identification, you will have been introduced to other keywords. There are also a - few additional points to consider.
This is only an example for learning purposes. Some additional constraints could be described. - For instance:
As an exercise, you can always try and add these constraints. It would probably require splitting - the schema further.
JSON Schema limits itself to describing the structure of JSON data, it cannot express functional - constraints.
If we take an NFS entry as an example, JSON Schema alone cannot check that the submitted NFS - server's hostname, or IP address, is actually correct: this check is left to applications.
While this is not a concern if you know that the schema you write will be used by you alone, you - should keep this in mind if you write a schema which other people can potentially use. The schema we - have written here has some features which can be problematic for portability:
Here is a basic example of a JSON Schema: -
-{ - "title": "Person", - "type": "object", - "properties": { - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - }, - "age": { - "description": "Age in years", - "type": "integer", - "minimum": 0 - } - }, - "required": ["firstName", "lastName"] -} -
The two examples below are step-by-step guides into building a schema: -
The Space Telescope Science Institute has also published a guide aimed at schema authors. -
JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.
The JSON document being validated or described we call the instance, and the document containing the description is called the schema.
The most basic schema is a blank JSON object, which constrains nothing, allows anything, and describes nothing:
{}
You can apply constraints on an instance by adding validation keywords to the schema. For instance, the "type" keyword can be used to restrict an instance to an object, array, string, number, boolean, or null:
{"type": "string"}
JSON Schema is hypermedia ready, and ideal for annotating your existing JSON-based HTTP API. JSON Schema documents are identified by URIs, which can be used in HTTP Link headers, and inside JSON Schema documents to allow recursive definitions.
Interested? Check out: -
Questions? Feeling helpful? Get involved on: -