JSON Schema

lastmod 2023-08-24created 2021-03-148 edits

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

Benefits

Describes your existing data format(s).
Provides clear human- and machine- readable documentation.
Validates data which is useful for:
- Automated testing.
- Ensuring quality of client submitted data.

Validation

The start of coding, TCP School - JSON Schema

Typical validation keywords available in JSON Schema are:

type - specifies the type of valid data.
properties - specifies pairs of valid data names and values.
required - valid only if it has every element of the specified array as a property.
minimum - only numbers greater than or equal to the minimum are valid.
maximum - only numbers less than or equal to the maximum are valid.
multipleOf - only multiples of the specified number are valid.
maxLength - only strings no longer than the specified maximum length are valid.
minLength - only strings at least the specified minimum length are valid.
pattern - only strings matching the specified regular expression are valid.

Numeric range validation

The following keywords let you specify the valid range of a number.

minimum - the minimum value the number can have
maximum - the maximum value the number can have
exclusiveMinimum - if true, the check excludes the value specified by the minimum keyword from the minimum value the number can have.
exclusiveMaximum - the maximum version of exclusiveMinimum.

The following example checks whether the data is an integer or real number greater than or equal to 1 (n>=1) and less than 10 (n<10).

{
    "type": "number",
    "minimum": 1,
    "maximum": 10,
    "exclusiveMaximum": true
}

String length validation

The minLength and maxLength keywords let you check whether the length of a string is valid.

The values of the minLength and maxLength keywords can only be positive numbers including 0.

The following example checks whether the length of the string is greater than 1 and less than 4.

{
    "type": "string",
    "minLength": 1,
    "maxLength": 4
}

String regular expression validation

{
    "type": "string",
    "pattern": "[a-z]+"
}

Required property validation for objects

The required keyword lets you specify the required properties an object must have.

If there is more than one required property, list the name of each required property in an array.

The following example checks whether the data is an object that has name and family as properties.

{
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "family": {"type": "string"},
        "age": {"type": "integer"},
        "weight": {"type": "number"}
    },
    "required": ["name", "family"]
}

Object property count validation

The minProperties and maxProperties keywords let you specify the minimum and maximum number of properties an object can have.

The following example checks whether the data is an object that has only 1 or 2 properties.

{
    "type": "object",
    "minProperties": 1,
    "maxProperties": 2
}

Array element validation

The items keyword lets you validate the elements stored in an array.

The following example checks whether the data is an array whose elements are all integers.

{
    "type": "array",
    "items": {
        "type": "integer"
    }
}

An example that validates each element of the array in order:

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "maxLength": 5
        },
        {
            "type": "string"
        },
        {
            "type": "string"
        }
    ]
}

In the case above, an array that has other elements in addition to the three valid elements will also pass validation.

If you set the value of the additionalItems keyword to false, an array with additional elements will not pass validation.

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "maxLength": 5
        },
        {
            "type": "string"
        },
        {
            "type": "string"
        }
    ],
    "additionalItems": false
}

Array length validation

The minItems and maxItems keywords let you specify the minimum and maximum length an array can have.

The following example checks whether the data is an array with 3 to 10 elements.

{
    "type": "array",
    "minItems": 3,
    "maxItems": 10
}

Array duplicate value validation

The uniqueItems keyword lets you specify whether duplicate values are allowed among the elements stored in an array.

If uniqueItems is true, duplicate values among the array elements can be disallowed.

The following example checks whether the data is an array whose element values are not duplicated.

{
    "type": "array",
    "uniqueItems": true
}

Boolean validation

{
    "type": "boolean"
}

JSON cannot use the numbers 1 and 0 in place of the booleans true and false, so the numbers 1 and 0 cannot pass in the example above.

null validation

If you set the value of the type keyword to null, it checks whether the data is null.

{
    "type": "null"
}

Enumerated data validation

Valid enum values are specified using an array and cannot contain duplicate values.

{
    "type": "string",
    "enum": ["웰시코기", "포메라니안", "푸들"]
}

Combining schemas

JSON Schema lets you combine multiple JSON schemas using the following keywords.

allOf

Must pass validation against all schemas listed in the array.

The following example checks whether the length of the string data is at least 3 and at most 5.

{
    "allOf": [
        {"minLength": 3},
        {"maxLength": 5}
    ]
}

anyOf

Must pass validation against one or more of the schemas listed in the array.

The following example checks whether the data is a string or a number.

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

oneOf

Must pass validation against exactly one of the schemas listed in the array.

The following example checks whether the data is a number that is a multiple of 3, or a number that is a multiple of 4.

{
    "oneOf": [
        { "type": "number", "multipleOf": 3 },
        { "type": "number", "multipleOf": 4 }
    ]
}

Only data that passes validation against exactly one of the two schemas will pass validation.

Multiples of 3 such as 3, 6, 9 pass
Multiples of 4 such as 4, 8, 16 pass
But common multiples of 3 and 4 such as 12, 24, 36 cannot pass validation.

not

The following example checks whether the data is not a string.

{
    "not": {
        "type": "string"
    }
}

Metadata

The metadata keywords that describe information about the schema are as follows.

title
description
default

Favorite site

author Zer0 sitemap