OpenAPI 3.3 Proposal: API-Level Deprecation & Sunset Support

[miqui]

Problem Statement
Currently, OpenAPI only supports deprecation at the operation level via the deprecated: boolean field on Operation Objects. There is no standard way to signal that an entire API is being deprecated or sunset.

This forces API providers to:

• Rely on prose in info.description (not machine-readable ???)
• Use non-standard x- extensions (not interoperable)
• Depend entirely on HTTP headers at runtime (consumers must actually call the API)
• Mark every single operation as deprecated individually

Proposed Solution
Add formal lifecycle management fields to OpenAPI, aligned with existing standards:

• RFC 8594: Sunset HTTP Header
• IETF Draft: Deprecation HTTP Header

Two Approaches
Approach A: New Root-Level lifecycle Object

openapi: "3.3.0"

lifecycle:
  stage: deprecated  # active | deprecated | sunset | deactivated
  stageDate: "2025-01-15T00:00:00Z"
  
  deprecation:
    date: "2025-01-15T00:00:00Z"
    reason: "Replaced by v2 API with improved performance"
    migration:
      description: Migration guide
      url: https://docs.example.com/migrate
    replacement:
      description: User API v2
      url: https://api.example.com/v2/openapi.yaml
    contact:
      name: Migration Team
      email: migrate@example.com
  
  sunset:
    date: "2025-07-01T00:00:00Z"
    policy:
      url: https://docs.example.com/sunset-policy
    gracePeriod: P30D  # ISO 8601 duration
  
  responseHeaders:
    Deprecation: "@1736899200"
    Sunset: "Tue, 01 Jul 2025 00:00:00 GMT"

Pros:

• Clean separation of concerns (info = what, lifecycle = status)
• Room for rich metadata without cluttering Info Object
• Mirrors how other specs handle lifecycle (e.g., API governance tools)

Cons:

• Largish? change to the spec
• New top-level object to learn

Approach B: Extend Info Object (Minimal Change)

info:
  title: User API (Legacy)
  version: "1.4.2"
  deprecated: true
  deprecationDate: "2025-01-15T00:00:00Z"
  sunsetDate: "2025-07-01T00:00:00Z"
  successorVersion: https://api.example.com/v2/openapi.yaml
  deprecationInfo: https://docs.example.com/deprecation/users-v1

Pros

• Minimal spec change
• Familiar location (Info Object already has metadata)
• deprecated: true mirrors operation-level pattern

Cons

• Mixes “what is this API” with “what’s happening to it”
• Limited space for rich migration information

---

Proposed Schema Additions

Lifecycle Object (Approach A)

Field	Type	Description
stage	string	Current lifecycle stage. Enum: active, deprecated, sunset, deactivated
stageDate	string (date-time)	When current stage began
deprecation	Deprecation Object	Deprecation details
sunset	Sunset Object	Sunset details
responseHeaders	Map[string, string]	Expected HTTP headers on responses

Deprecation Object

Field	Type	Description
date	string (date-time)	REQUIRED. When deprecation takes/took effect
reason	string	Human-readable explanation
migration	External Documentation Object	Link to migration guide
replacement	External Documentation Object	Link to replacement API
contact	Contact Object	Who to contact for help

Sunset Object

Field	Type	Description
date	string (date-time)	REQUIRED. When API stops accepting requests
policy	External Documentation Object	Link to sunset policy
gracePeriod	string (duration)	ISO 8601 duration for grace period

---

Info Object Extensions (Approach B)

Field	Type	Description
deprecated	boolean	Whether the entire API is deprecated
deprecationDate	string (date-time)	When deprecation takes effect
sunsetDate	string (date-time)	When API will stop accepting requests
successorVersion	string (uri)	URI to replacement API spec
deprecationInfo	string (uri)	URI to deprecation documentation

[miqui]

Hi friends, just a draft for now. Thoughts?