deprecated : Boolean

deprecated

Boolean

This keyword indicates that applications should refrain from using the declared property.

Value	This keyword must be set to a boolean value Hint: Use the `jsonschema metaschema` and `jsonschema lint` commands to catch keywords set to invalid values
Kind	Annotation
Applies To	Any
Base Dialect	2020-12
Changed In	None
Introduced In	2019-09
Vocabulary	Meta Data
Specification	https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.3
Metaschema	https://json-schema.org/draft/2020-12/meta/meta-data
Official Tests	None
Default	`false`
Annotation	Boolean The boolean value set by this keyword Hint: Use the `jsonschema validate` command to collect annotations from the command-line
Affected By	None
Affects	None
Also See	title (Vocabulary: Meta-Data) description (Vocabulary: Meta-Data) examples (Vocabulary: Meta-Data) default (Vocabulary: Meta-Data) readOnly (Vocabulary: Meta-Data) writeOnly (Vocabulary: Meta-Data)

The deprecated keyword, when set to true, signifies that an instance value (such as a specific object property) should not be used and may be removed or rejected in the future. This keyword does not affect validation, but the evaluator will collect its value as an annotation.

Best Practice

Avoid setting this keyword to the default value false. If an instance value is not considered to be deprecated, the best practice is to omit the use of this keyword altogether. This prevents unnecessarily generating and collecting an annotation that does not carry any additional meaning.

Common Pitfall

Tooling makers must be careful when statically traversing schemas in search of occurences of this keyword. It is possible for schemas to make use of this keyword behind conditional operators, references, or any other type of keyword that makes it hard or even impossible to correctly locate these values without fully evaluating the schema against an instance. The only bullet proof method is through annotation collection.

For example, an instance property might only be deprecated under certain conditions determined by a dynamic operator like anyOf.

Examples

A schema that statically marks the city optional object property as deprecated Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "country": { "type": "string" },
    "city": { "type": "string", "deprecated": true }
  }
}

Valid An object value that defines the deprecated property is valid but an annotation is emitted Instance

{ "country": "United Kingdom", "city": "London" }

Annotations

{ "keyword": "/properties/city/deprecated", "instance": "/city", "value": true }

Valid An object value that does not define the deprecated property is valid and no annotation is emitted Instance

{ "country": "United Kingdom" }

Invalid An object value that does not match the schema is invalid and no annotations are emitted Instance

{ "city": 1 }

A schema that dynamically marks the city optional object property as deprecated based on the presence of the country property Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "country": { "type": "string" },
    "city": { "type": "string" }
  },
  "dependentSchemas": {
    "country": {
      "properties": { "city": { "deprecated": true } }
    }
  }
}

Valid An object value that defines both properties is valid but an annotation is emitted Instance

{ "country": "United Kingdom", "city": "London" }

Annotations

{ "keyword": "/dependentSchemas/country/properties/city/deprecated", "instance": "/city", "value": true }

Valid An object value that only defines the city property is valid and no annotation is emitted Instance

{ "city": "London" }

Valid An object value that only defines the country property is valid and no annotation is emitted Instance

{ "country": "United Kingdom" }