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?
Add a comment
|
2 Answers
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.
Comments
Not currently, but it is planned for a future version of the specification. Discussion to the effect happened on https://github.com/json-schema-org/json-schema-spec/issues/74
Henry added it to the draft-future milestone in Sep 2017, but there are still issues to work out before we can get to it.
Update, see other answer regarding draft 2019-09 publication!
3 Comments
Abhay Dubey
Thanks for the quick reply. Can we safely assume that it will be available in the next draft? Is there a date published when the new draft will be available?
Relequestual
It won't make it into the next draft. Sorry. We have a maximum period of 6 months to release each draft. Some times we will aim sooner, but we have a lot of large complex issues to tackle, and it's difficult when almost everyone working on lives in a different time zone! Even if it DID make it into a next draft, libraries would have to implement it.
Relequestual
If you plan to do a staggered deprecation of fields, you could just put it in anyway and mention it in your API documentation, and suggest your schema consumers look for it... it just wouldn't be STANDARD. Any unknown key words are ignored.
