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 or using format for built-in validation supporting values date-time, date, time, email, hostname, uri, uri-reference
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]+"
}
Example of a date time field validation expecting values like 2019-10-20T19:30:11+00:00:
{
"type": "string",
"format": "date-time"
}
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" }
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
}
Enum¶
Enum supports exact value validation. Value is valid when enum array constains it.
Example of a enum containing various values of various types:
{
"enum": [ 1, 2, 2.5, "x", "y", true, false, null ]
}
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"
}
]
}
}