Schema

A schema is a document of type core.schema containing attributes:

  • target - document type to validate
  • content - JSON Schema

The system validates every document with internal schemas to ensure documents comply with the JSON API specification. There is no need to repeat such validation using schema documents. Schema documents are designed to enhance document validation based on the business rules of an application.

JSON API document representation in JSON Schema is an object with two sub-objects attributes and relationships:

{
  "type": "object",
  "properties": {
    "attributes": {
      "type": "object",
      "properties": {}
    },
    "relationships": {
      "type": "object",
      "properties": {}
    }
  }
}

Types

JSON Schema provides following types.

String

String type supports:

  • length validation - using minLength and maxLength where values must be positive integers
  • content validation - using pattern where a value is JavaScript ECMA 262 regular expression

Example of a username validation which should be a string consisted of at least 8 and at most 32 characters where the first character must be a letter followed by letters and/or numbers:

{
  "type": "string",
  "minLength": 8,
  "maxLength": 32,
  "pattern": "[a-z][a-z0-9]+"
}

Integer

Integer type supports:

  • range validation - using minimum and maximum where values must be numbers
  • scale validation - using multipleOf where value must be a number

Example of a number validation which should be an even integer in range [10, 100]:

{
  "type": "integer",
  "minimum": 10,
  "maximum": 100,
  "multipleOf": 2
}

Number

Number type supports:

  • range validation - using minimum and maximum where values must be numbers
  • scale validation - using multipleOf where value must be a number

Example of a price validation which should be a number with at most 2 decimal digits and should be in range [1, 10000]:

{
  "type": "number",
  "minimum": 1,
  "maximum": 10000,
  "multipleOf": 0.01
}

Boolean

Boolean type does not have options. Valid values are true and false.

Example:

{ "type": "boolean" }

Null

Null type does not have options. Valid value is only null.

Example:

{ "type": "null" }

Object

Object type supports:

  • structure validation - using properties object where a key is a property name and value is a property type definition
  • member validation - using required array where each item is a name of a property and additionalProperties boolean enabling properties not mentioned in structure

Example validation of a coordinate system representation where x and y axes are mandatory while z is optional:

{
  "type": "object",
  "properties": {
    "x": { "type": "number" },
    "y": { "type": "number" },
    "z": { "type": "number" }
  },
  "required": ["x" "y"],
  "additionalProperties": false
}

Array

Array type supports:

  • structure validation - using items object which defines type definition for each item in the array
  • length validation - using minItems and maxItems where values must be numbers
  • uniqueness validation - using uniqueItems boolean which when true mandates items to be unique in the array

Example validation of an array where each item in the array must be a string with a minimum length of 3 characters. There can be at least 1 item and at most 5 items where all must be unique.

{
  "type": "array",
  "items": {
    "type": "string",
    "minLength": 3
  },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}

Combinators

Combinators allow validation against one or more subschemas at the same time.

allOf

Combinator allOf accepts one or more subschemas where all must be satisfied to pass validation.

Example with two subschemas where the first specifies type string with a minimum length, while the second specifies type string with a pattern. Strings with a minimum length of 3 characters consisted of only letters will pass validation.

{
  "allOf": [
    {
      "type": "string",
      "minLength": 3
    },
    {
      "type": "string",
      "pattern": "[a-z]*"
    }
  ]
}

anyOf

Combinator anyOf accepts one or more subschemas where at least one must be satisfied to pass validation.

Example with two subschemas where first specifies type integer with a multiple of 10, while second specifies type integer with a minimum value of 10. Validation will pass all integers multiple of 10 and all integers greater than or equal to 100.

{
  "anyOf": [
    {
      "type": "integer",
      "multipleOf": 10
    },
    {
      "type": "integer",
      "minimum": 100
    }
  ]
}

oneOf

Combinator oneOf accepts one or more subschemas where exactly one must be satisfied to pass validation.

Example with two subschemas where first specifies type null, while second specifies type integer. A value will pass validation when is null or integer value.

{
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "integer"
    }
  ]
}

not

Combinator not accepts exactly one subschema where subschema must not be satisfied in order to pass validation (i.e. schema negation).

Example subschema specifies type null. All values except null will pass validation.

{
  "not": { "type": "null" }
}

Combinators can be nested. Using anyOf within not, more than one subschema can be specified which must not be satisfied. An example where anyOf contains two subschemas where one specifies type null and the other specifies type number. All values except for null and numbers will pass validation.

{
  "not": {
    "anyOf": [
      {
        "type": "null"
      },
      {
        "type": "number"
      }
    ]
  }
}