A Deprecation Manifest for Field-Level Lifecycle Signalling in HTTP APIs

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

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

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).¶

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:¶

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"
    }
  ]
}

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.¶

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].¶

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

9. References

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