Home GitHub Twitter
About Quick start
The Basics
Structure Generic keywords String type Number type Integer type Boolean type Null type Object type Array type Formats Default value Conditional subschemas Multiple subschemas
Reusability
References Definitions Pointers URI Templates
Advanced features
Variables Filters Mappers Slots Pragma Data
API
Validator Error formatter Schema loader Custom Filters Custom Formats Custom Media types Custom Content encodings Migration

Object type

Keywords for object type

Edit on GitHub

The object type is used for validating key-value maps (objects).

{
  "type": "object"
}
Input Status
{} valid - object with no properties
{"prop1": "val1", "prop2": 2.5} invalid
12 invalid - is integer/number
"some text" invalid - is string

Validation keywords

The following keywords are supported by the object type. All keywords are optional.

properties

An object is valid against this keyword if every property that is present in both the object and the value of this keyword, validates against the corresponding schema. The value of this keyword must be an object, where properties must contain valid json schemas (objects or booleans). Only the property names that are present in both the object and the keyword value are checked.

{
  "type": "object",
  "properties": {
    "a": {
      "type": "string"
    },
    "b": {
      "type": "integer"
    }
  }
}

Property a must be a string and property b must be an integer, if present.

Input Status
{"a": "str", "b": 5} valid
{"a": "str"} valid - a is a string
{"b": 5, "c": null} valid - c is an integer
{"prop1": 0, "prop2": "str"} valid - both a and b properties are missing
{"a": 1, "b": 5} invalid - a is not a string
{"a": 1, "b": "text"} invalid - a is not string and b is not an integer

required

An object is valid against this keyword if it contains all property names (keys) specified by the value of this keyword. The value of this keyword must be a non-empty array of strings representing property names.

{
  "type": "object",
  "required": ["a", "b"]
}

Object must have both a and b properties.

Input Status
{"a": 1, "b": 2, "c": 3} valid
{"a": 1, "b": null} valid
{"a": 1, "c": 3} invalid - property b is missing
{"c": 1, "d": 3} invalid - both a and b properties are missing

dependencies

An object is valid against this keyword if it mets all dependencies specified by this keyword value. The value of this keyword must be an object, where property values can be:

  • objects representing valid json schemas, and the whole object must match the entire schema.
    *Starting with draft 2019-09 you should use dependentSchemas keyword instead.
  • arrays of strings representing property names, then the object must contain all property names.
    *Starting with draft 2019-09 you should use dependentRequired keyword instead.

Only property names (from this keyword value) that are also present in the object are checked.

This keyword is not officially defined in draft-2019-09 and draft-2020-12, but we kept it for backward compatibility reasons.
This keyword was split into dependentSchemas keyword and dependentRequired keyword.
You can disable it for draft-2020-12 by setting the keepDependenciesKeyword option to false.

{
  "type": "object",
  "dependencies": {
    "a": ["b", "c"],
    "c": {
      "type": "object",
      "properties": {
        "b": {
          "type": "integer"
        }
      }     
    }
  }
}

If the object has property a, then it must also have b and c. If it has c then b can only be an integer.

Input Status
{"c": 1} valid - b is not required
{"c": 1, "b": 4} valid
{"a": 1, "b": 4, "c": 3, "d": true} valid
{"b": "str"} valid - no dependencies
{"c": 1, "b": "str"} invalid - b must be an integer
{"a": 1, "b": "str"} invalid - c is not present

dependentSchemas

An object is valid against this keyword if it mets all dependencies specified by this keyword value. The value of this keyword must be an object, where property values can be objects representing valid json schemas, and the whole object must match the entire schema.

Only property names (from this keyword value) that are also present in the object are checked.

{
  "type": "object",
  "dependentSchemas": {
    "c": {
      "type": "object",
      "properties": {
        "b": {
          "type": "integer"
        }
      }     
    }
  }
}

If the object has property c then property b can only be an integer.

Input Status
{"c": 1} valid - b is not required
{"c": 1, "b": 4} valid
{"b": "str"} valid - no dependencies
{"c": 1, "b": "str"} invalid - b must be an integer

dependentRequired

An object is valid against this keyword if it mets all dependencies specified by this keyword value. The value of this keyword must be an object, where property values must be arrays of strings representing property names, and the object must contain all property names.

Only property names (from this keyword value) that are also present in the object are checked.

{
  "type": "object",
  "dependentRequired": {
    "a": ["b", "c"]
  }
}

If the object has property a, then it must also have b and c.

Input Status
{"a": 1, "b": 4, "c": 3, "d": true} valid
{"a": 1, "b": "str"} invalid - c is not present

minProperties

An object is valid against this keyword if the number of properties it contains is greater then, or equal to, the value of this keyword. The value of this keyword must be a non-negative integer. Using 0 as a value has no effect.

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

Object must have at least 2 properties.

Input Status
{"a": "a", "b": "b", "c": "c"} valid - has 3 properties
{"a": "a", "b": "b"} valid - has 2 properties
{"a": "a"} invalid - has a single property
{} invalid - has no properties

maxProperties

An object is valid against this keyword if the number of properties it contains is lower then, or equal to, the value of this keyword. The value of this keyword must be a non-negative integer. Using 0 as a value means that the object must be empty (no properties).

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

Object can have at most 2 properties.

Input Status
{"a": "a", "b": "b"} valid - has 2 properties
{"a": "a"} valid - has a single property
{} valid - has no properties
{"a": "a", "b": "b", "c": "c"} invalid - has more than 2 properties

propertyNames

An object is valid against this keyword if every property name (key) is valid against the value of this keyword. The value of this keyword must be a valid json schema (an object or a boolean).

Please note that the value of propertyNames (the schema) will always test strings.

{
  "type": "object",
  "propertyNames": {
    "type": "string",
    "minLength": 2
  }
}

Every property name must have a minimum length of 2.

Input Status
{"prop1": 0, "prop2": "str"} valid
{} valid
{"prop": 1, "a": 2} invalid - length of a is smaller than 2

patternProperties

An object is valid against this keyword if every property where a property name (key) matches a regular expression from the value of this keyword, is also valid against the corresponding schema. The value of this keyword must an object, where the keys must be valid regular expressions and the corresponding values must be valid json schemas (object or boolean).

{
  "type": "object",
  "patternProperties": {
    "^str-": {
      "type": "string"
    },
    "^int-": {
      "type": "integer"
    }
  }
}

Every property name that starts with str- must be a string and every property name that starts with int- must be an integer.

Input Status
{"str-a": "a"} valid
{"int-i": 2} valid
{"int-i": 2, "str-a": "a", "other": [1, 2]} valid - other property is not matched
{"other": "a"} valid - no property was match
{"str-a": "a", "str-b": 2} invalid - str-b property is integer, not string
{"str-a": "a", "int-b": 2.5} invalid - int-b property is float, not integer

additionalProperties

An object is valid against this keyword if all unchecked properties are valid against the schema defined by the value of this keyword. Unchecked properties are the properties not checked by the properties and patternProperties keywords (if a property name is not present in properties keyword and doesn’t match any regular expression defined by patternProperties keyword, then it is considered unchecked). The value of this keyword must be a valid json schema (object or boolean).

To be more concise, if we have unchecked properties:

  • if the value of this keyword is true, is always valid
  • if the value is false, is never valid
  • if the value contains an object (schema), every property must be valid against that schema.
{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

Every property value of the object must be a string.

Input Status
{"a": "a", "b": "str"} valid
{} valid - no properties to check
{"str-a": "a", "int-b": 2} invalid - int-b is integer, not string 
{
  "type": "object",
  "properties": {
    "a": true,
    "b": true  
  },
  "additionalProperties": false
}

Object is invalid if contains other properties than a and b.

Input Status
{"a": "a", "b": "str"} valid
{"a": 1} valid
{} valid - no properties to check
{"a": "a", "c": 2} invalid - property c is not allowed
{"a": "a", "c": 2, "d": null} invalid - properties c and d are not allowed 
{
  "type": "object",
  "patternProperties": {
    "^a": true,
    "^b": true  
  },
  "additionalProperties": false
}

Object is invalid if property names doesn’t start with a or b.

Input Status
{"a": "a", "b": "str"} valid
{"aAA": "a", "bBB": "str"} valid
{"abc": "a"} valid
{} valid - no properties to check
{"abc": "a", "extra": 2} invalid - extra starts with an e
{"abc": "a", "Bcd": 2} invalid - Bcd starts with a B instead of b 
{
  "type": "object",
  "properties": {
    "a": true,
    "b": true
  },
  "patternProperties": {
    "^extra-": {
      "type": "string"
    }
  },
  "additionalProperties": {
    "type": "integer"
  }
}

Object is invalid if property names, exluding a and b and those starting with extra-, are not integers. Also, properties starting with extra- must be strings.

Input Status
{"a": "a", "b": "str"} valid
{"a": 1, "extra-a": "yes"} valid
{"a": 1, "extra-a": "yes", "other": 1} valid
{} valid - no properties to check
{"a": "a", "extra": 3.5, "other": null} invalid - extra and other must be integers
{"Extra-x": "x"} invalid - Extra-x does not start with extra-, so it must be an integer

unevaluatedProperties

An object is valid against this keyword if every unevaluated property is valid against the schema defined by the value of this keyword.

Unevaluated properties are the properties that were not evaluated anywhere in the current schema. This keyword can see through adjacent keywords, such as allOf.

This keyword is hard to follow when you are dealing with complex schemas. Also, it slows down the validation process because short-circuits must be disabled for this keyword to work correctly. We do not recommend using it, unless you fully understand its behavior!

{
  "type": "object",
  "properties": {
    "foo": {"type": "string"}
  },
  "allOf": [
    {
      "properties": {
          "bar": {"type": "string"}
      }
    }
  ],

  "unevaluatedProperties": false
}

Schema doesn’t allow unevaluated properties.

Input Status
{"foo": "foo", "bar": "bar"} valid - all evaluated
{"foo": "foo", "bar": "bar", "baz": "baz"} invalid - baz is unevaluated

You can disable unevaluatedProperties keyword by setting the allowUnevaluated option to false.

Description for null type

Null type

Keywords for array type

Array type
Copyright © Zindex Software. All rights reserved
On this page