"deprecation" property

[awwright]

Create a schema keyword that specifies an instance (property in an instance, usually) as deprecated -- it shouldn't be used, but exists only for internal use, or for reverse compatibility with obsolete or old products.

[handrews]

+1 to this. The point here, I assume, is for documentation and perhaps to allow implementations to issue warnings, rather than to affect validation.

[Relequestual]

Interesting proposal.

I know that JSON Schema isn't specifically for API's, but we should consider how API's might version their endpoints. Could this proposal actually be part of a seperate doc about API driven information. For example, included in deprecated, how it's deprecated and if it's replaced, and possibly other upgrade path type data.
Very much a straw man comment, not well thought through.

[handrews]

@Relequestual I'm not sure how far we want to chase the versioning idea here, but my approach to API evolution (rather than versioning) is to only change the version of the schema, and retain compatibility by (as much as possible) avoiding both required and "additionalProperties": false. I use the following rules:

• Resources add new schema versions to their list of profiles, and do not remove old versions
• If an instance validates against a schema that is a valid profile for the resource, no matter what version that schema is, than the instance can be used according to that version of the schema.
  • So if your code was written for a specific version, as long as that still validates, you can keep using that without worrying about the new version.
  • This can allow for continuing to function in a scenario where some new instances may not validate against the old schema, but if the instances you work with still validate, you don't have to update to support the things you don't need. For instance, a value was added to an enum, but you never use the new value.
• If you can't keep compatibility at all, make a new resource and handle the change through HATEOAS, use of 410 GONE, redirects, etc.
• There are no versions in the URI or primary media type (the schema versions likely show up in their profile URIs, since those need to be distinct somehow)

[Relequestual]

Interesting. Most of the time our API (and others I've worked on) have needed "new versions" because of new fields or new allowed values. Sometimes that's backwards compatible, but often it isn't for me, as much as I'd like it to be.

[handrews]

As long as you avoid setting additionalProperties to false, then new fields should be fine (unless you're generating strictly typed code off of the schemas without any provision for unrecognized fields, but I avoid that in favor of more generic client libraries).

Enumerations get tricky, but that's where the "if it still validates you can still use it" rule comes into play- technically the new version is not fully compatible but most instances will validate against either version.

My approach to API evolution is to do as much as possible to allow users to keep using the API as they have been unless their specific usage is broken by the update. It requires some design discipline, and the willingness to add a new resource as a replacement and deprecate the old instead of doing a major version change on the entire API and breaking a bunch of clients that don't actually care one way or the other.

[handrews]

Admittedly, I haven't actually had a chance to prove that this can work long-term, but it's something I'm trying with the current project I'm working on.

[Relequestual]

I think Protocol Buffers allows for flagging deprecation. If someone has time, may be worth seeing what that system allows for.

[awwright]

#173 is a sufficient solution for me, so I'll close this out in favor of the PR

[handrews]

@awwright please don't close issues while the corresponding PR is still open. PRs are not always accepted.