How do I mark a property in JSON schema as deprecated?

Question

I have a JSON schema that defines JSON documents. There's an use case where we want to deprecate a particular attribute in favour of a new attribute being introduced and want to mark the old attribute as deprecated. Does JSON schema support that?

Answer 1

Draft 2019-09 of the JSON Schema Validation spec, published on 2019-09-16, now defines the deprecated meta-data annotation:

The value of this keyword MUST be a boolean. When multiple occurrences of this keyword are applicable to a single sub-instance, applications SHOULD consider the instance location to be deprecated if any occurrence specifies a true value.

If "deprecated" has a value of boolean true, it indicates that applications SHOULD refrain from usage of the declared property. It MAY mean the property is going to be removed in the future.

A root schema containing "deprecated" with a value of true indicates that the entire resource being described MAY be removed in the future.

When the "deprecated" keyword is applied to an item in an array by means of "items", if "items" is a single schema, the deprecation relates to the whole array, while if "items" is an array of schemas, the deprecation relates to the corrosponding [sic] item according to the subschemas position.

Omitting this keyword has the same behavior as a value of false.