additionalProperties : Schema

additionalProperties

Schema

Validation succeeds if the schema validates against each value not matched by other object applicators in this vocabulary.

Value This keyword must be set to a valid JSON Schema
Kind Applicator Annotation
Applies To Object
Dialect 2020-12
Changed In None
Introduced In Draft 1
Vocabulary Applicator
Specification https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.3.2.3
Metaschema https://json-schema.org/draft/2020-12/meta/applicator
Official Tests draft2020-12/additionalProperties.json
Default {}
Annotation Array The set of instance property names validated by this keyword's subschema
Affected By
Affects
Also See

The additionalProperties keyword is used to control the handling of 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 behavior of this keyword depends on the presence and annotation results of properties and patternProperties within the same schema object. Validation with additionalProperties applies only to the child values of instance names that do not appear in the annotation results of either properties or patternProperties.

Examples

Schema with 'additionalProperties' set to boolean false Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "foo": { "type": "string" }
  },
  "additionalProperties": false
}
Valid An instance with no additional properties is valid Instance 
{ "foo": "foo" }
Annotations 
{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
Invalid An instance with additional properties is invalid Instance 
{ "foo": "foo", "bar": "bar" }
  • When additionalProperties is set to false, all the instance properties must either be present in the properties or match any regex within patternProperties; otherwise, the validaion will fail.
Schema with 'additionalProperties' set to an object schema Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "name": { "type": "string" }
  },
  "additionalProperties": {
    "type": "number"
  }
}
Valid An object instance with properties conforming to the schema is valid Instance 
{ "name": "John Doe", "age": 21 }
Annotations 
{ "keyword": "/properties", "instance": "", "value": [ "name" ] },
{ "keyword": "/additionalProperties", "instance": "", "value": [ "age" ] }
Invalid The value of 'age' must be a number Instance 
{ "name": "John Doe", "age": "21" }
  • The value of additionalProperties can either be a boolean schema or an object schema.
Schema with 'patternProperties', 'properties' and 'additionalProperties' keyword Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "patternProperties": {
    "[Aa]ge$": { "type": "number" }
  },
  "additionalProperties": true
}
Invalid The value of the 'name' property must be a string Instance 
{
  "name": [ "John", "Doe" ],
  "Age": 21,
  "email": "foo@bar.com"
}
Valid An object instance with properties conforming to the schema is valid Instance 
{
  "name": "John Doe",
  "Age": 21,
  "email": "foo@bar.com"
}
Annotations 
{ "keyword": "/properties", "instance": "", "value": [ "name" ] }
{ "keyword": "/patternProperties", "instance": "", "value": [ "Age" ] }
{ "keyword": "/additionalProperties", "instance": "", "value": [ "email" ] }
  • Instance properties (keys) not present in properties or not matching any regex within patternProperties are evaluated against additionalProperties.
Schema with no 'additionalProperties' defined Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "patternProperties": {
    "[Aa]ge$": { "type": "number" }
  }
}
Valid An object instance with properties conforming to the schema is valid Instance 
{
  "name": "John Doe",
  "Age": 21,
  "email": "foo@bar.com"
}
Invalid The value of 'Age' must be a number Instance 
{
  "name": "John Doe",
  "Age": "21",
  "email": "foo@bar.com"
}
Valid An object instance with additional properties is valid Instance 
{
  "name": "John Doe",
  "Age": 21,
  "email": [ "foo", "@", "bar", "com" ]
}
Annotations 
{ "keyword": "/properties", "instance": "", "value": [ "name" ] }
{ "keyword": "/patternProperties", "instance": "", "value": [ "Age" ] }

Note: JSON Schema is a constraint language and if you don’t limit keywords like this, then more keywords than what you defined in properties, etc would be allowed. If you don’t define a property using properties or patternProperties, but don’t disallow it with additionalProperties, it would still be valid with any value.