System
Light
DarkReference
object
Objects are the mapping type in JSON. They map "keys" to "values". In JSON, the "keys" must always be strings. Each of these pairs is conventionally referred to as a "property".
In Python, "objects" are analogous to the dict type. An
important difference, however, is that while Python dictionaries
may use anything hashable as a key, in JSON all the keys
must be strings.
Try not to be confused by the two uses of the word "object" here:
Python uses the word object to mean the generic base class for
everything, whereas in JSON it is used only to mean a mapping from
string keys to values.
schema
compliant to schemacompliant to schemaUsing non-strings as keys is invalid JSON:
not compliant to schemanot compliant to schemanot compliant to schemaProperties
The properties (key-value pairs) on an object are defined using the
properties keyword. The value of properties is an object, where each
key is the name of a property and each value is a schema used to
validate that property. Any property that doesn't match any of the
property names in the properties keyword is ignored by this keyword.
See Additional Properties and
Unevaluated Properties for how to disallow properties that
don't match any of the property names in properties.
For example, let's say we want to define a simple schema for an address made up of a number, street name and street type:
schemacompliant to schema// If we provide the number in the wrong type, it is invalid:
not compliant to schemaBy default, leaving out properties is valid. See Required Properties.
compliant to schemaBy extension, even an empty object is valid:
compliant to schemaBy default, providing additional properties is valid:
compliant to schemaPattern Properties
Sometimes you want to say that, given a particular kind of property
name, the value should match a particular schema. That's where
patternProperties comes in: it maps regular expressions to schemas. If
a property name matches the given regular expression, the property value
must validate against the corresponding schema.
Regular expressions are not anchored. This means that when defining the
regular expressions for patternProperties, it's important to note
that the expression may match anywhere within the property name. For
example, the regular expression "p" will match any property name with
a p in it, such as "apple", not just a property whose name is simply
"p". It's therefore usually less confusing to surround the regular
expression in ^...$, for example, "^p$".
In this example, any properties whose names start with the prefix S_
must be strings, and any with the prefix I_ must be integers. Any
properties that do not match either regular expression are ignored.
schemacompliant to schemacompliant to schemaIf the name starts with S_, it must be a string
not compliant to schemaIf the name starts with I_, it must be an integer
not compliant to schemaThis is a key that doesn't match any of the regular expressions:
compliant to schemaAdditional Properties
The additionalProperties keyword is used to control the handling of
extra stuff, that is, properties whose names are not listed in the
properties keyword or match any of the regular expressions in the
patternProperties keyword. By default any additional properties are
allowed.
The value of the additionalProperties keyword is a schema that will be
used to validate any properties in the instance that are not matched by
properties or patternProperties. Setting the additionalProperties
schema to false means no additional properties will be allowed.
Reusing the example from Properties, but this time setting
additionalProperties to false.
schemacompliant to schemaSince additionalProperties is false, this extra property "direction" makes the object invalid:
not compliant to schemaYou can use non-boolean schemas to put more complex constraints on the additional properties of an instance. For example, one can allow additional properties, but only if their values are each a string:
schemacompliant to schemaThis is valid, since the additional property's value is a string:
compliant to schemaThis is invalid, since the additional property's value is not a string:
not compliant to schemaYou can use additionalProperties with a combination of properties
and patternProperties. In the following example, based on the example
from patternProperties, we add a "builtin" property,
which must be a number, and declare that all additional properties (that
are neither defined by properties nor matched by patternProperties)
must be strings:
schemacompliant to schemaThis is a key that doesn't match any of the regular expressions:
compliant to schemaIt must be a string:
not compliant to schemaExtending Closed Schemas
It's important to note that additionalProperties only recognizes
properties declared in the same subschema as itself. So,
additionalProperties can restrict you from "extending" a schema
using combining keywords such as allOf. In
the following example, we can see how the additionalProperties can
cause attempts to extend the address schema example to fail.
schema"properties": { "type": { "enum": [ "residential", "business" ] } }, "required": ["type"]}
Fails additionalProperties. "type" is considered additional.
not compliant to schemaFails required. "type" is required.
not compliant to schemaBecause additionalProperties only recognizes properties declared in
the same subschema, it considers anything other than
"street_address", "city", and "state" to be additional. Combining
the schemas with allOf doesn't change that. A workaround
you can use is to move additionalProperties to the extending schema
and redeclare the properties from the extended schema.
schema"properties": { "street_address": true, "city": true, "state": true, "type": { "enum": [ "residential", "business" ] } }, "required": ["type"], "additionalProperties": false}
compliant to schemanot compliant to schemaNow the additionalProperties keyword is able to recognize all the
necessary properties and the schema works as expected. Keep reading to
see how the unevaluatedProperties keyword solves this problem without
needing to redeclare properties.
Unevaluated Properties
New in draft 2019-09In the previous section we saw the challenges with using
additionalProperties when "extending" a schema using
combining. The unevaluatedProperties keyword is similar
to additionalProperties except that it can recognize properties
declared in subschemas. So, the example from the previous section can be
rewritten without the need to redeclare properties.
schema"properties": { "type": { "enum": ["residential", "business"] } }, "required": ["type"], "unevaluatedProperties": false}
compliant to schemanot compliant to schemaunevaluatedProperties works by collecting any properties that are
successfully validated when processing the schemas and using those as
the allowed list of properties. This allows you to do more complex
things like conditionally adding properties. The following example
allows the "department" property only if the "type" of address is
"business".
schema"if": { "type": "object", "properties": { "type": { "const": "business" } }, "required": ["type"] }, "then": { "properties": { "department": { "type": "string" } } },
"unevaluatedProperties": false}
compliant to schemanot compliant to schemaIn this schema, the properties declared in the then schema only count
as "evaluated" properties if the "type" of the address is
"business".
Required Properties
By default, the properties defined by the properties keyword are not
required. However, one can provide a list of required properties using
the required keyword.
The required keyword takes an array of zero or more strings. Each of
these strings must be unique.
required must contain at least one string.
In the following example schema defining a user record, we require that each user has a name and e-mail address, but we don't mind if they don't provide their address or telephone number:
schemaProviding extra properties is fine, even properties not defined in the schema:
compliant to schemaMissing the required "email" property makes the JSON document invalid:
not compliant to schemaIn JSON a property with value null is not equivalent to the property not being present. This fails because null is not of type "string", it's of type "null"
not compliant to schemaProperty names
New in draft 6The names of properties can be validated against a schema, irrespective of their values. This can be useful if you don't want to enforce specific properties, but you want to make sure that the names of those properties follow a specific convention. You might, for example, want to enforce that all names are valid ASCII tokens so they can be used as attributes in a particular programming language.
schemacompliant to schemanot compliant to schemaSince object keys must always be strings anyway, it is implied that the
schema given to propertyNames is always at least:
schemaSize
The number of properties on an object can be restricted using the
minProperties and maxProperties keywords. Each of these must be a
non-negative integer.
schemanot compliant to schemanot compliant to schemacompliant to schemacompliant to schemanot compliant to schemaNeed Help?
Did you find these docs helpful?
Help us make our docs great!
At JSON Schema, we value docs contributions as much as every other type of contribution!
Still Need Help?
Learning JSON Schema is often confusing, but don't worry, we are here to help!.