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

[swapnil srivastava <[e-mail]>]

Hi Sami,

I am interested to work in this with you. Genuinely believe it will be
helpful.
Regarding you questions:

api-catalog: It is a fit as helpful to centralise the metadata about APIs.
Especially with rel="deprecation" to tell about contract changes and
schedules.
JSONPath / JSON Pointer: My vote is for JSON Pointer as it gives more power
to target changed areas inside a complex JSON structure like array indexes:
$.orders[*].items[*].legacy_property

On Thu, Aug 20, 2026 at 1:24 PM Sami Rmili <srmili=
[e-mail]> wrote:

> 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.--
> httpapi mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
>