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

["Salz, Rich" <[e-mail]>]

Has anyone reviewed or read this draft?

Is anyone interested in working on it?

On 6/29/26, 6:31 AM, "Sami Rmili" <srmili=[e-mail]> wrote:

Hi all,

I've posted a -00 that I'd appreciate feedback on: https://datatracker.ietf.org/doc/draft-rmili-httpapi-deprecation-manifest/<https://urldefense.com/v3/__https://datatracker.ietf.org/doc/draft-rmili-httpapi-deprecation-manifest/__;!!GjvTz_vk!UdbCGJgUkIk6zVouXXg3arFQdsx9VxS6qAI5K2NyVwiMCi3noKsByWtkXCggKLw6g0Rra6xB9I7GiqalbOVuvyiMrB3t$>

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://urldefense.com/v3/__https://osdm.io/spec/getting-started/__;!!GjvTz_vk!UdbCGJgUkIk6zVouXXg3arFQdsx9VxS6qAI5K2NyVwiMCi3noKsByWtkXCggKLw6g0Rra6xB9I7GiqalbOVuv2DClbZc$> (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,
--

[img]


Sami RMILI
Software Engineer
[e-mail]<mailto:[e-mail]>

16, boulevard Poissonnière - 75009 Paris, France


[linkedin]<https://urldefense.com/v3/__https://app.signitic.com/l/bVhvSkNYYlBaZ1lLQi8vejdqMlF4QT09-eFZMaExNZWZGQjMvaVVJaDArTTl6Zz09__;!!GjvTz_vk!UdbCGJgUkIk6zVouXXg3arFQdsx9VxS6qAI5K2NyVwiMCi3noKsByWtkXCggKLw6g0Rra6xB9I7GiqalbOVuv6-KRotI$> [web] <https://urldefense.com/v3/__https://app.signitic.com/l/bVhvSkNYYlBaZ1lLQi8vejdqMlF4QT09-VzNGNG5oU1pWYjZRMTVQMUxBZ2xJZz09__;!!GjvTz_vk!UdbCGJgUkIk6zVouXXg3arFQdsx9VxS6qAI5K2NyVwiMCi3noKsByWtkXCggKLw6g0Rra6xB9I7GiqalbOVuv4Kwx0gO$>




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