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

[Sami Rmili <[e-mail]>]

Rich, Sanjay,

Rich, thanks for the welcome. I wrote -00 in kramdown-rfc but built it by
hand, so I will set the draft up properly on i-d-template for -01, this is
all very new to me.

Sanjay, I'm excited to learn that this is of interest to you and I would
love to collaborate on this topic. One clarification though: the Link does
not point at the OpenAPI document. It points at the manifest, a small
document discovered at runtime from the resource being called via
rel="deprecation", which names the specific request or response member and
gives its deprecation and sunset dates.

Very happy to take a call on this, and a review whenever suits.

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$>


Le mer. 19 août 2026 à 19:39, Salz, Rich <rsalz=[e-mail]>
a écrit :

> Thanks for the note, and (a) welcome to the IETF and (b) congrats on your
> first draft. Looking at it, I assumed you used the i-d-template draft
> tooling, which is really what I’d recommend anyway :)
>
> I assume that things crossed in the mail, and that you saw Sanjay’s reply
> of being interested in this.
>
>
> On 8/19/26, 12:02 PM, "Sami Rmili" <srmili=[e-mail]>
> wrote:
>
> This Message Is From an External Sender
> This message came from outside your organization.
>
> Hi Rich,
>
> As far as I know I'm the only person interested in it so far, no reviews
> on-list.
>
> The need came out of our implementation of OSDM
> <https://urldefense.com/v3/__https://osdm.io/spec/getting-started/__;!!GjvTz_vk!Ue9_FeePWR43sPxergtKlliFtwyksA2jW65QqCH54gBe446hhuzBauL532WFPNzV2fXcCwawNvl2T7hSDbOjhiG_fibK$>
> (an open UIC rail-distribution API standard). The shared OpenAPI schema
> marks fields deprecated between minor versions, but that flag carries no
> dates and no single implementor can edit the shared schema to declare their
> own deployment's timeline. Ans as far as I could find, there's no standard
> way to say which field exactly is deprecated: RFC 9745 and RFC 8594 operate
> at the granularity of a resource, not a member inside a request or response
> body. That gap is the whole reason I wrote the draft.
>
> I'm actively trying to get OSDM to adopt this as we speak, so I do expect
> there to be real interest behind it. In the meantime I'd be very glad of a
> review of the draft.
> I should say this is my first time writing an Internet-Draft, so pointers
> on process are as welcome as technical comments. And I'm happy to explain
> the need in more detail, over a call too if that would help.
>
> 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$>
>
>
> Le mer. 19 août 2026 à 15:54, Salz, Rich <rsalz=
> [e-mail]> a écrit :
>
> 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.
>
>
> The content of this email is confidential and intended for the recipient
> specified in message only.
>

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