A message header to signal deprecation

[sdatspun2]

Hello,

I would like to find out if there is a need to provide a message header (like correleationId, contentType) that indicates to the subscribers of a channel that a message is using deprecated schema (if schema-aware). For HTTP APIs, there is an HTTP header https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/ in pre-RFC stage to convey deprecation. I wonder a message header in case of AsyncAPI would be useful to provide.

Thanks. sanjay

[derberg]

@sdatspun2 AsyncAPI is a protocol-agnostic specification that you can use to describe any kind of event-driven architecture. Sometimes using HTTP protocol, sometimes WebSocket, etc. So there is no AsyncAPI specific property that you should add to message header to specify deprecation as it highly depends on the technology that you use. For example, if you follow CloudEvents (combined with AsyncAPI) spec for messages, they are working on introducing a property dedicated to depracation information -> https://github.com/cloudevents/spec/pull/787/files. I guess in other cases folks do not think in categories of deprecation information in a message but they deprecate entire channels/topics.

Do you know what I mean? so it definitely highly depends IMHO on the protocol that you are using.

My assumption was you need it for technical reasons not to just render such information in docs.

[sdatspun2]

@derberg Deprecation of message payload (whole or part) is not a protocol specific aspect imo. Am I missing something?

[derberg]

@sdatspun2 no worries, it is probably missing come context.

Are you looking for a way to describe deprecation in the AsyncAPI file or have it in the message in the runtime? I assumed runtime.

[sdatspun2]

@derberg I initially did not think about docs but just like OpenAPI's deprecated flag, AsyncAPI would need similar flag too, no? Regarding runtime, my impression is that deprecation of schema for message payload (or even a header) is orthogonal to any protocol used to send a message. Like correlationId, a message header indicating deprecation would be useful.

[derberg]

OpenAPI's deprecated flag

yes, there is some discussion started but seems like there is not much interest -> https://github.com/asyncapi/spec/issues/305

message header indicating deprecation would be useful

definitely, but why do you expect it to be a part of AsyncAPI? I mean, in the end, message and header can be described with different formats, like header in the end is a schema, message payload can be json schema, can be avro schema, and can also be an openapi schema. AsyncAPI enables you to use any schema you want and does not tell you what fields you should have there in your payload or headers. Does it make sense?

Like correlationId

Yes, correlationId because of non standard approach to correlationId location and naming (some call it trackingId and I bet there are other names) has its individual place in the AsyncAPI file and works in the way that you specify there where someone can find info about correlationId. Main goal is tooling, so that tools have it easier to identify where given info is located.

So are you suggesting exactly the same for deprecation?

[sdatspun2]

So are you suggesting exactly the same for deprecation?

Yes, but not for the same reason (of tooling so that tools have it easier to identify where given info is located). Reason would be to convey to the subscriber(s) of a message that the message contains payload that is deprecated.

Glad to notice that Erik Wilde @dret was involved with #305.

[dret]

On 2021-10-25 23:03, Sanjay Dalal wrote:

Yes, but not for the same reason (of tooling so that tools have it easier to identify where given info is located). Reason would be to convey to the subscriber(s) of a message that the message contains payload that is deprecated.

wouldn't it be simpler (and maybe an easier overall model) to simply convey that the event is deprecated and may not be used in the future? we could simply replicate the lifecycle management that we have with sunset and deprecation, where these also are simple flags, but good enough for a consumer to understand that action needs to be taken.

[dret]

On 2021-11-02 00:46, Sanjay Dalal wrote:

@dret https://github.com/dret can you clarify about how to convey? in AsyncAPI doc or via a dedicated message header(s) at runtime? wouldn't it be simpler (and maybe an easier overall model) to simply convey that the event is deprecated and may not be used in the future?

we have to separate the what and how. my proposal is to only deprecate that a message is deprecated, meaning that it will not be emitted anymore at some point in time.

the how part is tricky, as has been pointed out, because AsyncAPI is not addressing "bindings". the easiest way would be to at least support such a flag in AsyncAPI so that in marketplaces and other design-time places it would be clear that the message shouldn't be used anymore. if/how that could map to runtime mechanisms, i am not quite sure.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[dret]

this has been inactive for quite a while now but i think it might be useful to think about if/how message deprecation is supported in AsyncAPI. my gut feeling would be to see this as a possible flag at the message level ("you may see messages like this, but please don't build new components emitting these messages").

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[dret]

probably still worth keeping this active to better support an "event lifecycle" in AsyncAPI. over at https://github.com/ietf-wg-httpapi/deprecation-header/issues/11 there's now the proposal to move away from "hard-coded" lifecycle stages as HTTP headers (such as Sunset and Deprecation) and to instead use a Lifecycle header. this model might be a really good match for AsyncAPI which could use the same general approach and have a Lifecycle property for messages where they could be labeled with stages such as experimental, production, deprecated, or sunset.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: