Objects are the mapping type in JSON. They map "keys" to "values".In JSON, the "keys" must always be strings. Each of these pairs isconventionally referred to as a "property".

schema

{"type":"object"}

data

{"key":"value","another_key":"another_value"}

compliant to schema

data

{"Sun":1.9891e30,"Jupiter":1.8986e27,"Saturn":5.6846e26,"Neptune":10.243e25,"Uranus":8.6810e25,"Earth":5.9736e24,"Venus":4.8685e24,"Mars":6.4185e23,"Mercury":3.3022e23,"Moon":7.349e22,"Pluto":1.25e22}

compliant to schema

Using non-strings as keys is invalid JSON:

data

{ 0.01:"cm", 1:"m", 1000:"km"}

not compliant to schema

data

"Not an object"

not compliant to schema

data

["An","array","not","an","object"]

not compliant to schema

Properties

The properties (key-value pairs) on an object are defined using thepropertieskeyword. The value ofproperties is an object, where eachkey is the name of a property and each value is aschema used tovalidate that property. Any property that doesn't match any of theproperty names in theproperties keyword is ignored by this keyword.

For example, let's say we want to define a simple schema for an addressmade up of a number, street name and street type:

schema

{"type":"object","properties":{"number":{"type":"number"},"street_name":{"type":"string"},"street_type":{"enum":["Street","Avenue","Boulevard"]}}}

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue"}

compliant to schema

// If we provide the number in the wrong type, it is invalid:

data

{"number":"1600","street_name":"Pennsylvania","street_type":"Avenue"}

not compliant to schema

By default, leaving out properties is valid. SeeRequired Properties.

data

{"number":1600,"street_name":"Pennsylvania"}

compliant to schema

By extension, even an empty object is valid:

data

{}

compliant to schema

By default, providing additional properties is valid:

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue","direction":"NW"}

compliant to schema

Pattern Properties

Sometimes you want to say that, given a particular kind of propertyname, the value should match a particular schema. That's wherepatternProperties comes in: it maps regular expressions to schemas. Ifa property name matches the given regular expression, the property valuemust validate against the corresponding schema.

In this example, any properties whose names start with the prefixS_must be strings, and any with the prefixI_ must be integers. Anyproperties that do not match either regular expression are ignored.

schema

{"type":"object","patternProperties":{"^S_":{"type":"string"},"^I_":{"type":"integer"}}}

data

{"S_25":"This is a string"}

compliant to schema

data

{"I_0":42}

compliant to schema

If the name starts withS_, it must be a string

data

{"S_0":42}

not compliant to schema

If the name starts withI_, it must be an integer

data

{"I_42":"This is a string"}

not compliant to schema

This is a key that doesn't match any of the regular expressions:

data

{"keyword":"value"}

compliant to schema

Additional Properties

TheadditionalProperties keyword is used to control the handling ofextra stuff, that is, properties whose names are not listed in theproperties keyword or match any of the regular expressions in thepatternProperties keyword. By default any additional properties areallowed.

The value of theadditionalProperties keyword is a schema that will beused to validate any properties in theinstance that are not matched byproperties orpatternProperties. Setting theadditionalPropertiesschema tofalse means no additional properties will be allowed.

Reusing the example fromProperties, but this time settingadditionalProperties tofalse.

schema

{"type":"object","properties":{"number":{"type":"number"},"street_name":{"type":"string"},"street_type":{"enum":["Street","Avenue","Boulevard"]}},"additionalProperties":false}

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue"}

compliant to schema

SinceadditionalProperties isfalse, this extra property "direction" makes the object invalid:

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue","direction":"NW"}

not compliant to schema

You can use non-boolean schemas to put more complex constraints on theadditional properties of an instance. For example, one can allowadditional properties, but only if their values are each a string:

schema

{"type":"object","properties":{"number":{"type":"number"},"street_name":{"type":"string"},"street_type":{"enum":["Street","Avenue","Boulevard"]}},"additionalProperties":{"type":"string"}}

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue"}

compliant to schema

This is valid, since the additional property's value is a string:

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue","direction":"NW"}

compliant to schema

This is invalid, since the additional property's value is not a string:

data

{"number":1600,"street_name":"Pennsylvania","street_type":"Avenue","office_number":201}

not compliant to schema

You can useadditionalProperties with a combination ofpropertiesandpatternProperties. In the following example, based on the examplefrompatternProperties, we add a"builtin" property,which must be a number, and declare that all additional properties (thatare neither defined byproperties nor matched bypatternProperties)must be strings:

schema

{"type":"object","properties":{"builtin":{"type":"number"}},"patternProperties":{"^S_":{"type":"string"},"^I_":{"type":"integer"}},"additionalProperties":{"type":"string"}}

data

{"builtin":42}

compliant to schema

This is a key that doesn't match any of the regular expressions:

data

{"keyword":"value"}

compliant to schema

It must be a string:

data

{"keyword":42}

not compliant to schema

Extending Closed Schemas

It's important to note thatadditionalProperties only recognizesproperties declared in the samesubschema as itself. So,additionalProperties can restrict you from "extending" a schemausingcombining keywords such asallOf. Inthe following example, we can see how theadditionalProperties cancause attempts to extend the address schema example to fail.

schema

{"allOf":[{"type":"object","properties":{"street_address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}},"required":["street_address","city","state"],"additionalProperties":false}],
"properties":{"type":{"enum":["residential","business"]}},"required":["type"]}

FailsadditionalProperties. "type" is considered additional.

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"business"}

not compliant to schema

Failsrequired. "type" is required.

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC"}

not compliant to schema

BecauseadditionalProperties only recognizes properties declared inthe same subschema, it considers anything other than"street_address", "city", and "state" to be additional. Combiningthe schemas withallOf doesn't change that. A workaroundyou can use is to moveadditionalProperties to the extending schemaand redeclare the properties from the extended schema.

schema

{"allOf":[{"type":"object","properties":{"street_address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}},"required":["street_address","city","state"]}],
"properties":{"street_address":true,"city":true,"state":true,"type":{"enum":["residential","business"]}},"required":["type"],"additionalProperties":false}

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"business"}

compliant to schema

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"business","something that doesn't belong":"hi!"}

not compliant to schema

Now theadditionalProperties keyword is able to recognize all thenecessary properties and the schema works as expected. Keep reading tosee how theunevaluatedProperties keyword solves this problem withoutneeding to redeclare properties.

Unevaluated Properties

New in draft 2019-09

In the previous section we saw the challenges with usingadditionalProperties when "extending" a schema usingcombining. TheunevaluatedProperties keyword is similartoadditionalProperties except that it can recognize propertiesdeclared in subschemas. So, the example from the previous section can berewritten without the need to redeclare properties.

schema

{"allOf":[{"type":"object","properties":{"street_address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}},"required":["street_address","city","state"]}],
"properties":{"type":{"enum":["residential","business"]}},"required":["type"],"unevaluatedProperties":false}

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"business"}

compliant to schema

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"business","something that doesn't belong":"hi!"}

not compliant to schema

unevaluatedProperties works by collecting any properties that aresuccessfully validated when processing the schemas and using those asthe allowed list of properties. This allows you to do more complexthings like conditionally adding properties. The following exampleallows the "department" property only if the "type" of address is"business".

schema

{"type":"object","properties":{"street_address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"type":{"enum":["residential","business"]}},"required":["street_address","city","state","type"],
"if":{"type":"object","properties":{"type":{"const":"business"}},"required":["type"]},"then":{"properties":{"department":{"type":"string"}}},
"unevaluatedProperties":false}

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"business","department":"HR"}

compliant to schema

data

{"street_address":"1600 Pennsylvania Avenue NW","city":"Washington","state":"DC","type":"residential","department":"HR"}

not compliant to schema

In this schema, the properties declared in thethen schema only countas "evaluated" properties if the "type" of the address is"business".

Required Properties

By default, the properties defined by theproperties keyword are notrequired. However, one can provide a list of required properties usingtherequired keyword.

Therequired keyword takes an array of zero or more strings. Each ofthese strings must be unique.

Draft-specific info

In Draft 4,required must contain at least one string.

In the following example schema defining a user record, we require thateach user has a name and e-mail address, but we don't mind if theydon't provide their address or telephone number:

schema

{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"address":{"type":"string"},"telephone":{"type":"string"}},"required":["name","email"]}

data

{"name":"William Shakespeare","email":"[email protected]"}

compliant to schema

Providing extra properties is fine, even properties not defined in the schema:

data

{"name":"William Shakespeare","email":"[email protected]","address":"Henley Street, Stratford-upon-Avon, Warwickshire, England","authorship":"in question"}

compliant to schema

Missing the required "email" property makes the JSON document invalid:

data

{"name":"William Shakespeare","address":"Henley Street, Stratford-upon-Avon, Warwickshire, England",}

not compliant to schema

In JSON a property with valuenull is not equivalent to the property not being present. This fails becausenull is not of type "string", it's of type "null"

data

{"name":"William Shakespeare","address":"Henley Street, Stratford-upon-Avon, Warwickshire, England","email":null}

not compliant to schema

Property names

New in draft 6

The names of properties can be validated against a schema, irrespectiveof their values. This can be useful if you don't want to enforcespecific properties, but you want to make sure that the names of thoseproperties follow a specific convention. You might, for example, want toenforce that all names are valid ASCII tokens so they can be used asattributes in a particular programming language.

schema

{"type":"object","propertyNames":{"pattern":"^[A-Za-z_][A-Za-z0-9_]*$"}}

data

{"_a_proper_token_001":"value"}

compliant to schema

data

{"001 invalid":"value"}

not compliant to schema

Since object keys must always be strings anyway, it is implied that theschema given topropertyNames is always at least:

schema

{"type":"string"}

Size

The number of properties on an object can be restricted using theminProperties andmaxProperties keywords. Each of these must be anon-negative integer.

schema

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

data

{}

not compliant to schema

data

{"a":0}

not compliant to schema

data

{"a":0,"b":1}

compliant to schema

data

{"a":0,"b":1,"c":2}

compliant to schema

data

{"a":0,"b":1,"c":2,"d":3}

not compliant to schema