A Deprecation Manifest for Field-Level Lifecycle Signalling in HTTP APIs
draft-rmili-httpapi-deprecation-manifest-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Sami Rmili | ||
| Last updated | 2026-06-26 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-rmili-httpapi-deprecation-manifest-00
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: <https://api.example/.deprecations>; 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,
<https://www.rfc-editor.org/rfc/rfc9745>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/rfc/rfc8259>.
[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,
<https://www.rfc-editor.org/rfc/rfc9535>.
[JSONPOINTER]
Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
DOI 10.17487/RFC6901, April 2013,
<https://www.rfc-editor.org/rfc/rfc6901>.
[LINK] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/rfc/rfc8288>.
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,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/rfc/rfc3339>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/rfc/rfc6838>.
[RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
Structured Syntax Suffixes", RFC 6839,
DOI 10.17487/RFC6839, January 2013,
<https://www.rfc-editor.org/rfc/rfc6839>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
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,
<https://www.rfc-editor.org/rfc/rfc9727>.
[JSONSCHEMA]
"JSON Schema: A Media Type for Describing JSON Documents",
June 2022,
<https://json-schema.org/draft/2020-12/json-schema-core>.
[OPENAPI] "OpenAPI Specification v3.1.0", February 2021,
<https://spec.openapis.org/oas/v3.1.0>.
[PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
<https://www.rfc-editor.org/rfc/rfc9457>.
[RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers
(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
<https://www.rfc-editor.org/rfc/rfc8615>.
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,
<https://www.rfc-editor.org/rfc/rfc8594>.
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]