Deprecating an entire object

[felixdesouza]

Motivation

We have deprecation of fields, enums and endpoints. It feels like a natural extension to deprecate entire objects that shouldn't be used anymore. Can we extend the deprecation syntax to objects too?

Proposal

That is:

Metadata:
  deprecated: Use MetadataV2 instead etc.
  docs: Bla
  fields: 
    field1: string
    field2: string

Could go even further and add deprecation notices to the methods of deprecated objects, I don't think it comes up otherwise. But at the very least it'd be nice to have it baked in similar to fields, enums and endpoints.

I can throw something up if it's a reasonable proposal?

[bmarcaur]

+1 From much of the Gotham ecosystem, we cycle and deprecate objects fairly frequently and this would be a nice QOL improvement.

[rhysbrettbowen]

Also services

[jamesross3]

Perhaps scope bloat, but making conjure server implementations consult the deprecated field for endpoints when serving requests and potentially adding an informative response header (smt like Conjure-Deprecated-Endpoint: true) could aid deprecation/removal efforts by unblocking telemetry for deprecated usage.

[carterkozak]

We set a Deprecation header already! https://github.com/palantir/conjure-java/blob/develop/conjure-java-undertow-runtime/src/main/java/com/palantir/conjure/java/undertow/runtime/DeprecationReportingResponseHandler.java

Dialogue clients warn when the server responds with a deprecation header here: https://github.com/palantir/dialogue/blob/develop/dialogue-core/src/main/java/com/palantir/dialogue/core/DeprecationWarningChannel.java

[ash211]

I've found some conjure object definitions with docs: Deprecated, use OtherObjectType. type fields, where clearly the dev was trying to communicate that a whole object was deprecated.

It would be helpful to better communicate this with a structured deprecated: field, so language generators can mark the whole object as deprecated, and e.g. in IntelliJ you'd see deprecation warnings on the object.