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

[Sanjay Dalal <[e-mail]>]

Thanks Rich. I have not reviewed it but I am quite familiar with the
problem. In fact, Erik and I intentionally scoped out the specific
request/response members from RFC 9745 since it could be addressed with
OpenAPI's deprecated flag and extension. Not sure if Link pointing to the
openapi document for the API would suffice to address the need here
instead. I am interested in knowing more about the real need and help/work
with Sami Ramili to advance it if appropriate.

On Wed, Aug 19, 2026 at 6:54 AM Salz, Rich <rsalz=
[e-mail]> wrote:

> 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,
> --
>
> [image: img]
>
> *Sami RMILI*
> *Software Engineer*
> [e-mail]
>
> 16, boulevard Poissonnière - 75009 Paris, France
> [image: linkedin]
> <https://urldefense.com/v3/__https://app.signitic.com/l/bVhvSkNYYlBaZ1lLQi8vejdqMlF4QT09-eFZMaExNZWZGQjMvaVVJaDArTTl6Zz09__;!!GjvTz_vk!UdbCGJgUkIk6zVouXXg3arFQdsx9VxS6qAI5K2NyVwiMCi3noKsByWtkXCggKLw6g0Rra6xB9I7GiqalbOVuv6-KRotI$> [image:
> 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.
> --
> httpapi mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
>