HTTPAPI S. Rmili Internet-Draft Wiremind Intended status: Standards Track 26 June 2026 Expires: 28 December 2026 A Deprecation Manifest for Field-Level Lifecycle Signalling in HTTP APIs draft-rmili-httpapi-deprecation-manifest-00 Abstract The Deprecation and Sunset HTTP response header fields, defined in RFC 9745 and RFC 8594 respectively, let a server signal that a resource, identified by its URI, has been or will be deprecated and when it will be removed. They operate at the granularity of a resource and cannot describe the lifecycle of an individual member within a request or response representation. This document defines the "application/deprecations+json" media type, a machine-readable Deprecation Manifest in which an API operator declares dated deprecation and sunset timelines for specific members of request and response representations. The manifest is discovered through the existing "deprecation" link relation type and is decoupled from any API description or schema, allowing each deployment to publish its own timeline without changing the wire behaviour of the API. About This Document This note is to be removed before publishing as an RFC. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-rmili-httpapi-deprecation- manifest/. Discussion of this document takes place on the HTTPAPI Working Group mailing list (mailto:httpapi@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/httpapi/. Subscribe at https://www.ietf.org/mailman/listinfo/httpapi/. Source for this draft and an issue tracker can be found at https://github.com/sarmili/deprecation-manifest. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Rmili Expires 28 December 2026 [Page 1] Internet-Draft Deprecation Manifest June 2026 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 28 December 2026. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 2. The Deprecation Manifest . . . . . . . . . . . . . . . . . . 4 2.1. The Deprecation Entry Object . . . . . . . . . . . . . . 5 2.1.1. The target Member . . . . . . . . . . . . . . . . . . 6 2.1.2. The direction Member . . . . . . . . . . . . . . . . 6 2.1.3. The selector and selectorType Members . . . . . . . . 6 2.1.4. The deprecation and sunset Members . . . . . . . . . 6 3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Relationship to the Deprecation and Sunset Header Fields . . 7 5. Resource Behaviour . . . . . . . . . . . . . . . . . . . . . 8 6. Limitations . . . . . . . . . . . . . . . . . . . . . . . . . 8 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 8.1. The "application/deprecations+json" Media Type . . . . . 9 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 9.2. Informative References . . . . . . . . . . . . . . . . . 11 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 Rmili Expires 28 December 2026 [Page 2] Internet-Draft Deprecation Manifest June 2026 1. Introduction HTTP APIs evolve. A common evolution is to introduce a new representation member that replaces an older one, while continuing to accept or return the older member for a transition period. The operator of such an API needs to communicate, to the consumers of the API, that the older member is on its way out and the date after which it will no longer be supported. The Deprecation HTTP response header field [DEPRECATION] and the Sunset HTTP response header field [SUNSET] address this need at the granularity of a _resource_: they describe the resource identified by the request URI. They do not, and by design cannot, name an individual member inside a JSON request or response body. HTTP header fields describe the message or the resource, not the substructure of a representation. At the same time, the mechanisms that _can_ name an individual member, namely the deprecated keyword of the OpenAPI Specification [OPENAPI] and of JSON Schema [JSONSCHEMA], are design-time annotations baked into a single shared description. They carry no date, and they describe the contract rather than a particular deployment of it. An operator who supports a shared, multi-party API specification cannot use them to express "on _my_ deployment, this member will stop being accepted on this date". No existing mechanism combines all three properties that this situation requires: 1. member-level granularity (which field, not just which resource); 2. dated lifecycle (a deprecation date and a sunset date); and 3. per-deployment, runtime discoverability (decoupled from the schema). This document fills that gap with a Deprecation Manifest: a JSON document, served with the "application/deprecations+json" media type, in which an operator declares dated deprecation and sunset information for individual members of request and response representations. The manifest reuses the date semantics of [DEPRECATION] and [SUNSET] and is discovered through the "deprecation" link relation type registered by [DEPRECATION]. The manifest is purely informational. It does not alter the behaviour of any resource, and conformance to it imposes no requirement on a server to accept or reject any particular member (see Section 5). Rmili Expires 28 December 2026 [Page 3] Internet-Draft Deprecation Manifest June 2026 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. This document uses the term "member" as defined by [JSON]: a name/ value pair within a JSON object. The terms "consumer" and "operator" refer, respectively, to a client of an HTTP API and to the party that operates the server. 2. The Deprecation Manifest A Deprecation Manifest is a JSON [JSON] document whose media type is "application/deprecations+json" (Section 8.1). Its root is a JSON object with the following members: +==============+=======+==========+==============================+ | Member | Type | Required | Description | +==============+=======+==========+==============================+ | deprecations | array | yes | An array of Deprecation | | | | | Entry objects (Section 2.1). | +--------------+-------+----------+------------------------------+ Table 1 A consumer MUST ignore any member it does not recognise. An operator MAY include additional members; this document does not define their meaning. { "deprecations": [ { "target": "POST /offers", "direction": "request", "selector": "$.tripDetails.legacyFare", "replacedBy": "$.tripDetails.fare", "deprecation": "2026-01-01", "sunset": "2026-12-31", "info": "https://api.example/migration/legacy-fare" } ] } Figure 1: An example Deprecation Manifest Rmili Expires 28 December 2026 [Page 4] Internet-Draft Deprecation Manifest June 2026 2.1. The Deprecation Entry Object Each element of the deprecations array is a Deprecation Entry: a JSON object describing the lifecycle of a single member, identified by a selector (Section 2.1.3), within the representations of a single target (Section 2.1.1). +==============+========+==========+=============================+ | Member | Type | Required | Description | +==============+========+==========+=============================+ | target | string | yes | Identifies the operation or | | | | | resource the entry applies | | | | | to (Section 2.1.1). | +--------------+--------+----------+-----------------------------+ | direction | string | yes | "request" or "response" | | | | | (Section 2.1.2). | +--------------+--------+----------+-----------------------------+ | selector | string | yes | Locates the deprecated | | | | | member (Section 2.1.3). | +--------------+--------+----------+-----------------------------+ | selectorType | string | no | "jsonpath" (default) or | | | | | "jsonpointer" | | | | | (Section 2.1.3). | +--------------+--------+----------+-----------------------------+ | replacedBy | string | no | A selector, of the same | | | | | selectorType, for the | | | | | replacement member. | +--------------+--------+----------+-----------------------------+ | deprecation | string | no | The date the member is or | | | | | was deprecated | | | | | (Section 2.1.4). | +--------------+--------+----------+-----------------------------+ | sunset | string | no | The date after which the | | | | | member will no longer be | | | | | supported (Section 2.1.4). | +--------------+--------+----------+-----------------------------+ | info | string | no | A URI of human-readable | | | | | documentation about the | | | | | deprecation. | +--------------+--------+----------+-----------------------------+ | description | string | no | A short human-readable | | | | | explanation. | +--------------+--------+----------+-----------------------------+ Table 2 Rmili Expires 28 December 2026 [Page 5] Internet-Draft Deprecation Manifest June 2026 2.1.1. The target Member The target member identifies the operation or resource to which the entry applies. Its value is a string. When the operation is best identified by an HTTP method and a path, the value SHOULD be the method (in uppercase) followed by a single space and a path or path template, for example "POST /offers" or "GET /offers/{offerId}". An operator MAY use any other stable identifier its consumers can resolve; the meaning of such identifiers is out of scope for this document. 2.1.2. The direction Member The direction member indicates whether the selector applies to the representation a consumer _sends_ in a request ("request") or to the representation a server _returns_ in a response ("response"). A consumer MUST treat an entry whose direction it does not recognise as having no defined meaning and SHOULD ignore it. 2.1.3. The selector and selectorType Members The selector member locates the deprecated member within the relevant representation. The interpretation of selector is governed by selectorType: * "jsonpath" (the default when selectorType is absent): selector is a JSONPath expression as defined in [JSONPATH]. * "jsonpointer": selector is a JSON Pointer as defined in [JSONPOINTER]. A consumer that does not implement the indicated selectorType MUST ignore the entry. The replacedBy member, when present, uses the same selectorType as the entry's selector. This document defines selectors only for representations whose media type is JSON [JSON] or a media type using the structured "+json" suffix. Selectors for other media types are out of scope (Section 6). 2.1.4. The deprecation and sunset Members The deprecation member carries the date on which the member is, or was, deprecated; it MAY be in the past or the future. The sunset member carries the date after which the operator intends to stop supporting the member. These members reuse, at member granularity, the semantics of the Deprecation [DEPRECATION] and Sunset [SUNSET] header fields respectively. Rmili Expires 28 December 2026 [Page 6] Internet-Draft Deprecation Manifest June 2026 The value of each is a string containing a date, or a date and time, formatted as a full-date or date-time as defined in [RFC3339]. A consumer MUST NOT assume that the absence of a sunset member implies any particular removal date. 3. Discovery A server makes a Deprecation Manifest discoverable by means of the "deprecation" link relation type registered by [DEPRECATION]. Where [DEPRECATION] uses that relation to point to human-readable documentation, this document allows the same relation to point to a machine-readable manifest, distinguished by its media type. A server MAY include, in HTTP [HTTP] responses or in a resource representation, a link ([LINK]) with relation type "deprecation" and a type target attribute of "application/deprecations+json" whose target URI is a Deprecation Manifest: Link: ; rel="deprecation"; type="application/deprecations+json" A consumer that retrieves the linked manifest can determine, for the members it sends or receives, whether any is deprecated and when it is scheduled to be sunset, without parsing per-response signals. A server MAY also make a manifest available at a stable, operator- chosen URI advertised out of band. The definition of a well-known URI [RFC8615] for this purpose is left to future work. Publishing API metadata as a document that is discovered through a link relation or a well-known URI is an established pattern; the api- catalog well-known URI [APICATALOG] is one example. 4. Relationship to the Deprecation and Sunset Header Fields For deprecation at the granularity of a resource, the Deprecation [DEPRECATION] and Sunset [SUNSET] header fields remain the mechanism of choice. They are conveyed in band, on a response the consumer is already retrieving, and require no additional request. This document does not change or supersede them. Rmili Expires 28 December 2026 [Page 7] Internet-Draft Deprecation Manifest June 2026 The Deprecation Manifest addresses the case those header fields cannot express: the deprecation of an individual member within a representation. An entry MAY omit its selector to describe a whole resource, but this is a convenience that lets an operator list resource-level and member-level deprecations in one place; it is not intended to replace the header fields. Where a resource is described both by a header field and by a manifest entry, the two are expected to convey consistent dates. 5. Resource Behaviour Consistent with [DEPRECATION], the presence of an entry in a Deprecation Manifest does not change the behaviour of any resource. A member that is listed as deprecated, and even one whose sunset date has passed, may still be accepted or returned by the server. The manifest expresses the operator's _intent_; it is advisory metadata and imposes no protocol-level requirement on either party. Consumers are advised to migrate away from a deprecated member before its sunset date. 6. Limitations The scope of this document is constrained as follows: * It defines a _proactive_, out-of-band declaration. It does not define an _in-band_ signal that names, within a specific response, a deprecated member that the consumer used in the corresponding request. The Deprecation and Sunset header fields describe the resource, not a body member, and Problem Details [PROBLEM] is defined for error conditions, whereas an accepted-but-deprecated member is not an error. In-band member-level signalling is left to future work or to ecosystem-specific conventions. * It defines selectors for JSON representations only. * It does not provide a means to authenticate the manifest beyond the transport-level protections discussed in Section 7. 7. Security Considerations A Deprecation Manifest is a hint and SHOULD be treated as such; see the corresponding considerations in [DEPRECATION]. Rmili Expires 28 December 2026 [Page 8] Internet-Draft Deprecation Manifest June 2026 A manifest, or a "deprecation" link advertising one, that is obtained over an unsecured channel may be forged or altered by an intermediary, for example to suppress a sunset date or to point a consumer at misleading documentation. Consumers SHOULD obtain manifests over an authenticated, integrity-protected channel and SHOULD verify that the info and manifest URIs belong to the expected operator. Because acting on a future-dated sunset automatically (for example by disabling a code path) can cause a consumer to stop sending a member earlier than necessary, consumers SHOULD surface such dates to their developers rather than enforce them without review. 8. IANA Considerations 8.1. The "application/deprecations+json" Media Type IANA is requested to register the following media type in the "Media Types" registry, per [RFC6838]. Type name: application Subtype name: deprecations+json Required parameters: N/A Optional parameters: N/A Encoding considerations: binary; the content is a JSON [JSON] document encoded in UTF-8. Security considerations: See Section 7 of RFC XXXX. Interoperability considerations: See RFC XXXX. Published specification: RFC XXXX Applications that use this media type: HTTP API clients and servers that exchange member-level deprecation information. Fragment identifier considerations: As specified for the "+json" suffix in [RFC6839]. Additional information: Deprecated alias names for this type: N/A Magic number(s): N/A File extension(s): N/A Rmili Expires 28 December 2026 [Page 9] Internet-Draft Deprecation Manifest June 2026 Macintosh file type code(s): N/A Person and email address to contact for further information: Sami Rmili (srmili@wiremind.io) Intended usage: COMMON Restrictions on usage: N/A Author: Sami Rmili Change controller: IETF 9. References 9.1. Normative References [DEPRECATION] Dalal, S. and E. Wilde, "The Deprecation HTTP Response Header Field", RFC 9745, DOI 10.17487/RFC9745, March 2025, . [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [JSONPATH] Gössner, S., Ed., Normington, G., Ed., and C. Bormann, Ed., "JSONPath: Query Expressions for JSON", RFC 9535, DOI 10.17487/RFC9535, February 2024, . [JSONPOINTER] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . [LINK] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . Rmili Expires 28 December 2026 [Page 10] Internet-Draft Deprecation Manifest June 2026 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, DOI 10.17487/RFC6839, January 2013, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 9.2. Informative References [APICATALOG] Smith, K., "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs", RFC 9727, DOI 10.17487/RFC9727, June 2025, . [JSONSCHEMA] "JSON Schema: A Media Type for Describing JSON Documents", June 2022, . [OPENAPI] "OpenAPI Specification v3.1.0", February 2021, . [PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, . [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, . Rmili Expires 28 December 2026 [Page 11] Internet-Draft Deprecation Manifest June 2026 [SUNSET] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, DOI 10.17487/RFC8594, May 2019, . Acknowledgements This work was inspired by the Deprecation [DEPRECATION] and Sunset [SUNSET] HTTP header fields and by the practical needs of operators of multi-party HTTP API specifications. Author's Address Sami Rmili Wiremind Email: srmili@wiremind.io Rmili Expires 28 December 2026 [Page 12]