additionalProperties : Schema

additionalProperties

Schema

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

Kind Applicator Annotation
Applies To Object
Dialect 2020-12
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
Affected By
Also see

Annotations

The annotation result of this keyword is the set of instance property names validated by this keyword.

Explanation

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.

  • The value of additionalProperties must be a valid JSON Schema.
  • Each property value of this object must be a valid JSON Schema.
  • The annotation result of this keyword is the set of instance property names validated by this keyword’s subschema.
  • This annotation affects the behavior of unevaluatedProperties in the Unevaluated vocabulary.
  • Omitting this keyword has the same assertion behavior as an empty object.

Examples

Schema with 'additionalProperties' set to boolean false Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "foo": { "type": "string" }
  },
  "additionalProperties": false
}
An instance with no additional properties is valid Instance
{ "foo": "foo" }
Annotations
[
  // ...
  {
    "valid": true,
    "keywordLocation": "/properties",
    "instanceLocation": "",
    "annotation": [ "foo" ]
  },
  // ...
]
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"
  }
}
An object instance with properties conforming to the schema is valid Instance
{ "name": "John Doe", "age": 21 }
Annotations
[
  // ...
  {
    "valid": true,
    "keywordLocation": "/properties",
    "instanceLocation": "",
    "annotation": [ "name" ]
  },
  {
    "valid": true,
    "keywordLocation": "/additionalProperties",
    "instanceLocation": "",
    "annotation": [ "age" ]
  },
  // ...
]
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
}
The value of the 'name' property must be a string Instance
{
  "name": [ "John", "Doe" ],
  "Age": 21,
  "email": "foo@bar.com"
}
An object instance with properties conforming to the schema is valid Instance
{
  "name": "John Doe",
  "Age": 21,
  "email": "foo@bar.com"
}
Annotations
[
  // ...
  {
    "valid": true,
    "keywordLocation": "/properties",
    "instanceLocation": "",
    "annotation": [ "name" ]
  },
  {
    "valid": true,
    "keywordLocation": "/patternProperties",
    "instanceLocation": "",
    "annotation": [ "Age" ]
  },
  {
    "valid": true,
    "keywordLocation": "/additionalProperties",
    "instanceLocation": "",
    "annotation": [ "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" }
  }
}
An object instance with properties conforming to the schema is valid Instance
{
  "name": "John Doe",
  "Age": 21,
  "email": "foo@bar.com"
}
The value of 'Age' must be a number Instance
{
  "name": "John Doe",
  "Age": "21",
  "email": "foo@bar.com"
}
An object instance with additional properties is valid Instance
{
  "name": "John Doe",
  "Age": 21,
  "email": [ "foo", "@", "bar", "com" ]
}
Annotations
[
  // ...
  {
    "valid": true,
    "keywordLocation": "/properties",
    "instanceLocation": "",
    "annotation": [ "name" ]
  },
  {
    "valid": true,
    "keywordLocation": "/patternProperties",
    "instanceLocation": "",
    "annotation": [ "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.