[FEATURE REQUEST] Channel deprecation/sunset

[fmvilas]

It would be great to have a way to flag that a channel is deprecated or is going to disappear/sunset at some point. We already thought about a property like deprecated: true but that would be insufficient if we want to understand when the channel is going to finally disappear and what alternatives do I have.

I thought on something like this, following a bit the idea behind the sunset header definition for HTTP by @dret.

deprecated: true
sunset:
  datetime: 2020-01-21T18:33:19Z # Optional
  message: Stop using it now! # Optional
  externalDocs: myjira.com/issue-7 # Optional (Thanks Michael Davis)
  alternativeChannel: /alternative/channel/name # Optional

I'm sure some folks over at JSON Schema and OpenAPI already had this discussion. Any thoughts? @philsturgeon @MikeRalphson @Relequestual

Source of discussion here: https://asyncapi.slack.com/archives/C34F2JV0U/p1579542224002900

[philsturgeon]

There's also the Deprecation header from the same author. https://tools.ietf.org/html/draft-dalal-deprecation-header-02

Although a group effort like anything in these projects, I was tasked with figuring out how we'd do deprecation in JSON Schema 2019-09, and settled for deprecated: true. This was mostly to match OpenAPI and not introduce more divergence, but there was a lot of other thinking behind it.

When Which How Version

Whenever the conversation came up, it started as: "Let's just have a boolean!"

deprecated: true

Then it was "we also need a reason"

deprecated: "We removed this endpoint, use some other endpoint" 

Then the conversation would branch and some people would start trying to figure out how to describe the endpoint (in your case channel, or for JSON Schema a property).

deprecated: 
  message: "We are getting rid of the foo channel because it's replaced with bar"
  channel: bar

Others would care less about that and move into "we also need to know when it will be deprecated, the actual date" then somebody else argues versions are better, and the people involved decide that the best solution is both:

```yaml
deprecatedSince: 2020-01-01
deprecatedAt: 2020-02-01
deprecatedVersionSince: v1.5
deprecatedVersionForRemoval: v2.0

Design Time vs Runtime

Ugh. I didn't see a single one of these conversations go well, and in the end I figured: look, we can use deprecated: true as a hint that this thing is likely not long for this world, then they can look at the HTTP message to see if there is a Deprecation or Sunset to get the rest of the information.

Afterall, it is easy for me to write up a description document that says "this thing is going in two months" but oh dammit some million dollar client hit a roadblock and they're gonna need it for another month.

Or, the plan was to make it last another year then we found an issue that made us want to ramp that up, 80% of clients are off it, so lets push that date forward a little.

Unless everyone involved is very much entirely on top of their sh*t, the chances of a prediction being entirely correct and never needing to change is... low. As such I'd rather emit all the specifics at runtime, instead of shoving it into descriptions which could be distributed and not updated for a while.

tldr: IHMO deprecated: true is fine. 👍

[dret]

On 2020-01-23 12:14, Phil Sturgeon wrote: There's also the Deprecation header from the same author. https://tools.ietf.org/html/draft-dalal-deprecation-header-02

i was going to point to that one. thanks, phil.

Whenever the conversation came up, it started as: "Let's just have a boolean!" deprecated:true

so, our thinking was to say "at the very least, you want to able to signal upcoming deprecations", so we added a date. we make it very clear that this is a hint and not a promise or threat: the actual date might change. but once it is in the past, the API clearly is in "it was deprecated back then" state. and then we stopped branching into scenarios because it seemed like they were quickly diverging into a complex universe of machine- and human-targeted ideas.

[derberg]

Back in days I worked for a few years on a platform for publishing microservices, we had marketplace and all that stuff so you can imagine we had hundreds of different APIs and we used RAML. The pain was exactly when we new we have to deprecate something. We ended up with writing information manually in release notes, and we had a plan to invent a kind of notification system where we would put proper data about deprecation in a machine-readable format. If we would already have all of those in a specification writing such notification center would be much better as we already had all those services in a system and they all were exposing RAML files on the root of the service.

My suggestion is:

deprecated:
  sunset: 2020-01-21T18:33:19Z # Optional 
  reason: Stop using it now! # Required
  externalDocs: myjira.com/issue-7 # Optional (Thanks Michael Davis)

• deprecated: # not boolean but an object, if it is there in the spec for me it is like true
• sunset: this is how we called the closing of the above-mentioned platform :) and it is also a word that has a bit positive "sound". This would be date fields like in the HTTP header proposal
• reason: I like it more than a "message" or a "description". I took it from https://www.apollographql.com/docs/graphql-tools/schema-directives/. This would be required field
• externalDocs: great suggestion by Michael, I would use it in the above described use case as a field where I provide a link to release notes with more details and migration instruction
• alternativeChannel: this is a detail that should be in release notes, or in a reason if someone is too lazy. I can't imagine what I can use this field for programmatically. I would not automatically switch to a new channel, deprecations are things that need closer manual attention.

---

[rv0]

I like where this is heading and the idea of all the extra properties is very good and we would most definitely use a lot of the optional ones..

The sunset property can be confusing though, especially for people that are not native english speakers. (I always found it a confusing word myself).
I would use a more descriptive property like for example "endDate", "purgeDate", "removalDate", ...

Externaldocs as plural suggests an array payload instead of string

[MikeRalphson]

@fmvilas sorry I never replied to the above, must have missed it. I believe these are the currently open related OAS issues:

• Add info.lifecycle with maturity/lifecycle informations. OAI/OpenAPI-Specification#1973
• Adding support for 'deprecatedSince' and 'since' OAI/OpenAPI-Specification#1616
• Enhanced Operation Deprecation and versioning OAI/OpenAPI-Specification#782

[Relequestual]

I don't believe we've looked to address this in JSON Schema.
It would be nice to have it uniformly across API specs and JSON Schema.
I'm open to anything we can get agreement on which is useful.
As @dret noted, there are some existing draft standards for this. @philsturgeon wrote an article which links to both and has some good points for discussion: https://blog.stoplight.io/deprecating-api-endpoints