JSON Schema

JSON Schema is a standard to define and validate the structure and constraints of JSON data.

Configuration files
API responses
Language agnostic types

JSON Schema Implementations

IDE Autocomplete


VS Code
Visual Studio
IntelliJ

JSON Schema libraries

JSON Schema — Tools

JSON Schema Format

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",         
  "$schema" specifies the version of the JSON Schema standard
 JSON Schema Docs — $schema 
Advanced — 11 collapsed lines
    "$vocabulary": { 
        "https://json-schema.org/draft/2020-12/vocab/core": true,
        "https://json-schema.org/draft/2020-12/vocab/applicator": true,
        "https://json-schema.org/draft/2020-12/vocab/validation": true,
        "https://json-schema.org/draft/2020-12/vocab/unevaluated": true,
        "https://json-schema.org/draft/2020-12/vocab/format-annotation": true,
        "https://json-schema.org/draft/2020-12/vocab/format-assertion": true,
        "https://json-schema.org/draft/2020-12/vocab/content": true,
        "https://json-schema.org/draft/2020-12/vocab/meta-data": true,
        ...          
  "$vocabulary" allows to extend JSON schema with custom keywords

 JSON Schema Docs — Vocabularies list 
Since  Draft 2019-09
    }, 
    "$id": "https://stephcraft.net/schema/demo.json",       
The  URL at which the schema is hosted · optional 

 JSON Schema Docs — Unique identifier 
    "title": "Demo",
    "description": "learn JSON schema at https://stephcraft.net/docs/json-schema",           
The  title and  description of the schema · optional
    "type": "object",       
  "type" can be one of:

 object
 array
 string
 number
 boolean
 null

Alternatively,  enum or  const can be used
Example schema — 17 collapsed lines
    "properties": { 
        "value":    { "type":  "number"             },
        "enabled":  { "type":  "boolean"            },
        "text":     { "type":  "string"             },
        "nothing":  { "type":  "null"               },
        "zero":     { "const": 0                    },
        "category": { "enum":  ["release", "draft"] },
        "tags":     { "type":  "array"              },
        "nested": {
            "type": "object",
            "properties": {
                "first": { "type": "string" },
                "last":  { "type": "string" }
            }
        }
    },
    "required": ["value", "enabled"] 
}

Example Usage

JSON Schema is supported by JSON · YAML · TOML

JSON

{
    "$schema": "./schema.json",
    "value": 115,
    "enabled": true,
    "text": "hello world",
    "nothing": null,
    "zero": 0,
    "category": "stable",
    "tags": ["cool", "awesome", "fantastic"],
    "nested": {
        "first": "Gordon",
        "last": "Freeman"
    }
}

YAML

# $schema: ./schema.json
value: 115
enabled: true
text: hello world
tags: [cool, awesome, fantastic]
nothing: null
zero: 0
category: stable
nested:
    first: Gordon
    last: Freeman

TOML

"$schema" = "./schema.json"
value = 115
enabled = true
text = "hello world"
nothing = "null"
zero = 0
category = "stable"
tags = ["cool", "awesome", "fantastic"]

[nested]
first = "Gordon"
last = "Freeman"

Versions


Draft 2020-12	`"https://json-schema.org/draft/2020-12/schema"`	Jun 2022	Latest
Draft 2019-09	`"https://json-schema.org/draft/2019-09/schema"`	Sep 2019

Legacy Drafts


Draft 7	`"https://json-schema.org/draft/draft-07/schema"`	Mar 2018
Draft 6	`"https://json-schema.org/draft/draft-06/schema"`	Apr 2017
Draft 4	`"https://json-schema.org/draft/draft-04/schema"`	Oct 2016
Draft 3	`"https://json-schema.org/draft/draft-03/schema"`	Nov 2010
Draft 2	`"https://json-schema.org/draft/draft-02/schema"`	Mar 2010
Draft 1	`"https://json-schema.org/draft/draft-01/schema"`	Dec 2009
Draft 0	`"https://json-schema.org/draft/draft-00/schema"`	Dec 2009

JSON Schema Docs — Drafts

Types

Const

{ "const": "zero" }      
Value must be it 

 JSON Schema Docs — const

Enum

{ "enum": ["pink", "blurple", false, null, ...] }     
Value must be one of the specified options 

 JSON Schema Docs — enum

Null

{ "type": "null" }             
Value must be null 

 JSON Schema Docs — null

Boolean

{ "type": "boolean" }               
Value of true or false 

 JSON Schema Docs — boolean

Number

{
    "type": "number",                
 "type" can be either:

"number" Value must be a number 1.0
"integer" Value must be a whole number 1

 JSON Schema Docs — numeric 
    "minimum": 0,
    "maximum": 100,
    "exclusiveMinimum": 0,
    "exclusiveMaximum": 100,             
 Range constraints can be defined

"minimum" ≥ value ≥ "maximum"
"exclusiveMinimum" > value > "exclusiveMaximum"

 JSON Schema Docs — numeric range
    "multipleOf" : 10,          
 Multiple constraint can be defined 

 JSON Schema Docs — numeric multiples 
}

String

{
    "type": "string",                
Value of text "..." 

 JSON Schema Docs — string 
    "minLength": 1,
    "maxLength": 10,          
 Length constraints can be defined 

 JSON Schema Docs — string length 
    "pattern": "^[a-z]+$"         
 Regex constraint can be defined 

 JSON Schema Docs — string regex 
Regular Expressions 
}

Array

{
    "type": "array",                
Value of a list [...] 

 JSON Schema Docs — array 
    "minItems": 1,
    "maxItems": 5,         
 Length constraints can be defined 

 JSON Schema Docs — array length 
    "uniqueItems": true,           
 Uniqueness constraint can be defined 

 JSON Schema Docs — array uniqueness 
    "items": { "type": "number", ... },        
 Type constraint can be defined for the array items 

 JSON Schema Docs — array items 
Advanced — 11 collapsed lines
    "contains": { "type": "number", ... }, 
    "minContains": 1,
    "maxContains": 3,           
Alternatively,  Type constraints can be defined for a certain amount of items 

 JSON Schema Docs — array contains 
    "prefixItems": [
        { "type": "string",  ... },
        { "type": "number",  ... },
        { "type": "boolean", ... },
        ...
    ],
    "items": false,        
Alternatively,  Type constraints can be defined for each of the items 


Setting  "items" to true only applies the schema for the first items and allows additional items
Setting  "items" to false applies the schema to all items and doesn't allow additional items

 JSON Schema Docs — array tuple validation¶ 
    "unevaluatedItems": false              
 Additional items constraint outside of  "items",  "contains" and  "prefixItems" can be defined 

 JSON Schema Docs — array unevaluated items 
}

Object

{
    "type": "object",                
Value of an object {...} 

 JSON Schema Docs — object 
    "properties": {
        "id":      { "type": "string",  ... },
        "enabled": { "type": "boolean", ... },
        "value":   { "type": "number",  ... },
        ...          
 Schema constraints can be defined 

 JSON Schema Docs — object properties 
    },
    "required": ["id", "enabled", ...],         
 Required properties constraints can be defined 

 JSON Schema Docs — object required properties 
Advanced — 12 collapsed lines
    "minProperties": 1, 
    "maxProperties": 10,            
 Length constraints can be defined 

 JSON Schema Docs — object size 
    "patternProperties": {
        "^S_": { "type": "string", ... },
        "^N_": { "type": "number", ... },
        ...          
 Regex property pattern constraints can be defined 

 JSON Schema Docs — object pattern properties 
    },
    "propertyNames": {
        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"             
 Regex property name constraint can be defined 

 JSON Schema Docs — object property names 
    },
    "unevaluatedProperties": false,                
 Additional properties constraint outside of  "properties" and  "patternProperties" can be defined 

 JSON Schema Docs — object unevaluated properties 
    "additionalProperties": { "type": "string", ... },                 
Additional properties  Type constraint can be defined 

 JSON Schema Docs — object additional properties 
}

Dependent properties

{
    "type": "object",
    "dependentRequired": {              
A map of  properties that when present, applies further  required properties 

 JSON Schema Docs — Dependent required 
        "username": [ "handle", "avatar", ... ],
        ...
    },
    "dependentSchemas": {             
A map of  properties that when present, applies further  schemas 

 JSON Schema Docs — Dependent Schemas 
        "username": {
Example schema — 5 collapsed lines
            "properties": { 
                "handle": { "type": "string", "pattern": "@.+"    },
                "avatar": { "type": "string", "pattern": "http.+" }
            },
            "required": [ "handle", "avatar" ] 
        },
        ...
    }
}

Features

Annotations

Annotations state the intent of the schema, they don’t add any constraints to the data being validated.

{ "$comment": "...", ... }        
JSON Schema comment 

 JSON Schema Docs — comments

{
    "title": "...",
    "description": "...",           
 Property annotations

 "title" The  Title of the schema

 "description" The  Description of the schema

    "default": null,
    "examples": ["zombie", 115, ...],         
 Value annotations

 "default" The  default value of the property

 "examples" The  example values of the property

    "deprecated": true,
    "readOnly": true,
    "writeOnly": false     Flag annotations

 "deprecated" Whether the property is  deprecated · marked for removal

 "readOnly" Whether the property is  read only · immutable

 "writeOnly" Whether the property is  write only · secret

}

String Content Annotations

String Media

{
    "type": "string",
    "contentMediaType": "image/png",             
 Media Type can be any MIME type  

 JSON Schema Docs — Media content media type 
    "contentEncoding": "base64",             
 Encoding can be one of:

null · UTF-8 
"base64" 
"base32" 
"base16" · hexadecimal 
"quoted-printable" · ASCII encoding 

 JSON Schema Docs — Media content encoding 
}

String Schema

{
    "type": "string",
    "contentMediaType": "application/json",             
When used with a content schema,  Media Type can be one of:

"application/json"  Supported
"application/yaml"  Unofficial
"application/toml"  Unofficial
    "contentSchema": {            
A  JSON Schema can be specified for the string's content 

 JSON Schema Docs — Media content schema 
Example schema — 5 collapsed lines
        "type": "object", 
        "properties": {
            "alg": { "type": "string" },
            "typ": { "const": "JWT" }
        } 
    }
}

Conditional Schema

{
    "type": "object",
    "if": {
Example schema — 3 collapsed lines
        "properties": { 
            "enabled": { "const": true }                 
Equivalent to if enabled == true
        } 
    },
    "then": {
Example schema — 3 collapsed lines
        "properties": { 
            "text": { "minLength": 15 }
        } 
    },
    "else": {
Example schema — 3 collapsed lines
        "properties": { 
            "text": { "minLength": 1 }
        } 
    }     
Conditionally apply schemas

if that  schema is  validated
then that  schema is applied
else that  schema is applied · optional

 JSON Schema Docs — If then else 
}

Boolean Schema composition

{
    "allOf": [        
 AND · all  schemas must be satisfied
Example schemas — 2 collapsed lines
        { "$comment": "This is a comment" }, 
        { "$comment": "And this is another comment" } 
    ],
    "anyOf": [        
 OR · at least one  schema must be satisfied
Example schemas — 8 collapsed lines
        { 
            "$comment": "default suggestions",
            "enum": [ "html", "svg", "math" ]
        },
        {
            "$comment": "enum is not exhaustive, allow custom values",
            "type": "string",
        } 
    ],
    "oneOf": [        
 XOR · one  schema must be satisfied and none of the rest
Example schemas — 9 collapsed lines
        { 
            "properties": {
                "x": { "type": "number" },
                "y": { "type": "number" },
                "z": { "type": "number" }
            },
            "required": [ "x", "y", "z" ]
        },
        { "type": "number" } 
    ],
    "not": {       
 NOT · this  schema must not be satisfied
Example schema — 3 collapsed lines
        "license_plate": { 
            "enum": [ "NULL", "DROP", "DELETE" ]
        } 
    }
}

Modular Schema composition

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/schema.json",       
Relative  file path references are resolved relative to the  base URL of the root schema  "$id"

https://example.com

 JSON Schema Docs — Base URI 
    "type": "object",
    "properties": {
        "location": { "$ref": "#/$defs/geolocation" },                         
 Subschemas can be referenced by  "$defs" inline definitions
        "position": { "$ref": "/schemas/vector.json" },                         
 Schemas can be referenced by relative or absolute  file path
        "website":  { "$ref": "/schemas/types.json#/properties/url" },                         
 Subschemas can be referenced by  schema paths within a schema
        "contact":  { "$ref": "/schemas/types.json#email" },                         
 Subschemas can be referenced by  schema anchors within a schema
        "tree":     { "$ref": "#" }                         
 Schemas can be recursively self-referenced
    },

    "$defs": {        
 "$defs" allows  subschemas to be defined in the same file 

 JSON Schema Docs — $defs 
        "geolocation": {
Example schema — 5 collapsed lines
            "type": "object",  
            "properties": {
                "longitude": { "type": "number" },
                "latitude": { "type": "number" }
            } 
        },
        "vector": {
            "$id": "https://example.com/schemas/vector.json",               
Specifying  "$id" in a subschema indicates an embedded  schema

Embedded schemas can be referenced as if they were external schemas

 JSON Schema Docs — Bundling 
Example schema — 6 collapsed lines
            "type": "object",  
            "properties": {
                "x": { "type": "number" },
                "y": { "type": "number" },
                "z": { "type": "number" }
            } 
        },
        "types": {
            "$id": "https://example.com/schemas/types.json",
            "type": "object",
            "properties": {
                "url": {
Example schema — 2 collapsed lines
                    "type": "string",  
                    "pattern": "http.+" 
                },
                "email": {
                    "$anchor": "email",                         
Specifying  "$anchor" allows to reference subschemas using:

the  anchor alias · #id
instead of its  schema path · #/properties/...

 JSON Schema Docs — $anchor 
Example schema — 2 collapsed lines
                    "type": "string", 
                    "pattern": "^.+@.+\\..+$" 
                }
            }
        },
        ...
    }
}