[httpapi] New draft: draft-rmili-httpapi-deprecation-manifest-00 (field-level deprecation signalling)

[Sami Rmili <[e-mail]>]

Hi all,

I've posted a -00 that I'd appreciate feedback on:
https://datatracker.ietf.org/doc/draft-rmili-httpapi-deprecation-manifest/

*The gap:*
 The Deprecation (RFC 9745) and Sunset (RFC 8594) header fields signal
lifecycle at the granularity of a resource. They cannot, by design, name an
individual member inside a JSON request or response body. The mechanisms
that can name a member, the deprecated keyword in OpenAPI and JSON Schema
are design-time, carry no dates, and live in a single shared description.
So an operator of a multi-party API spec has no standard way to say "on my
deployment, this particular field stops being accepted on this date."

*The proposal: *
 An *application/deprecations+json* document,  a "*Deprecation Manifest*"
in which an operator declares dated deprecation and sunset timelines for
specific request/response members. It's discovered via the existing
*rel="deprecation"* link relation, is decoupled from any API description,
and is purely informational, it never changes the wire behaviour of a
resource. It reuses the date semantics of RFC 9745/8594 rather than
replacing them.

*Origin:*
 This comes from a real need as an implementor/contributor of OSDM
<https://osdm.io/spec/getting-started/> (an open UIC rail-distribution API
standard). The OpenAPI schema is shared by everyone who implements the
standard, and it evolves: between two minor versions, a field gets marked
deprecated in favour of a replacement. But that deprecated flag in the
shared schema is undated, and no single implementor can edit the shared
schema to add their own dates. So even though the standard says a field is
on its way out, each operator is left with no standard way to declare when
their own deployment will stop accepting or returning it (i.e. its actual
deprecation and sunset dates). The manifest lets each implementor publish
that per-deployment timeline without touching the shared contract. I expect
to ship one in the OSDM ecosystem, which should give the design some
running code to evaluate.

I'd particularly welcome views on whether this belongs as a discovery
document alongside RFC 9727 (api-catalog), and on the selector design
(JSONPath / JSON Pointer).

Thanks,
-- 

[image: img]

*Sami RMILI*
*Software Engineer*
[e-mail]

16, boulevard Poissonnière - 75009 Paris, France
[image: linkedin]
<https://app.signitic.com/l/bVhvSkNYYlBaZ1lLQi8vejdqMlF4QT09-eFZMaExNZWZGQjMvaVVJaDArTTl6Zz09>
[image:
web]
<https://app.signitic.com/l/bVhvSkNYYlBaZ1lLQi8vejdqMlF4QT09-VzNGNG5oU1pWYjZRMTVQMUxBZ2xJZz09>

-- 
The content of this email is confidential and intended for the recipient 
specified in message only.