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

[Henry Andrews <[e-mail]>]

 It's worth noting that in OpenAPI-land, we are spinning off a Lifecycle specification to work on concepts related to this.  It will be a separate specification but not a separate JSON/YAML description document.  We are just modularizing the specification.  This work is just getting started and the main discussion is at https://github.com/OAI/sig-lifecycle/discussions/5
thanks,-henry


    On Thursday, August 20, 2026 at 02:24:09 AM PDT, 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,
--
| 
| 

 | 
| 
Sami RMILI
Software Engineer
[e-mail]

16, boulevard Poissonnière - 75009 Paris, France
 |
| 
|  |  |

 |

 |

 |




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 SenderThis 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 (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,--
| 
| 

 | 
| 
Sami RMILI
Software Engineer
[e-mail]

16, boulevard Poissonnière - 75009 Paris, France
 |
| 
|  |  |

 |

 |

 |



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/

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 existingrel="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 ofOSDM (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,--
| 
| 

 | 
| 
Sami RMILI
Software Engineer
[e-mail]

16, boulevard Poissonnière - 75009 Paris, France
 |
| 
|  |  |

 |

 |

 |


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]