[miqui]

Summary

This PR brings the Lifecycle Specification in line with the SAF mechanism merged in OAI/OpenAPI-Specification#5447. It builds the Lifecycle Object on the Docs Links proposal, and replaces the stub schema with a real one. It supersedes #15.

SAF framing (operation-scoped, per discussion #5)

• The Lifecycle Object describes one operation's deprecation and sunset. It is not a document-wide object; applying it across many operations is left to Overlays.
• Adds a mapping from Lifecycle Object fields to the Deprecation (RFC 9745), Sunset (RFC 8594), and Link headers, and an informative appendix on AI agent / MCP use.

Alignment with OAS #5447

• A document opts in through the root features map (features: { security: 1.0.0, lifecycle: 1.0.0 }). The spec notes that security must be listed explicitly once features is set.
• The Lifecycle Object lives in a dedicated Operation Object lifecycle field, not in an operation-level features. This avoids reusing the root features name with a different type.

Adopting externalLinks (Docs Links proposal)

• Breaking, pre-1.0.0: migration, replacement, and sunset.policy are replaced by a single lifecycle.externalLinks array of External Documentation Objects.
• kind is required on each entry. deprecation, successor-version, and sunset are IANA link relation names, so each link maps directly to Link: <url>; rel="<kind>". Other kinds (for example changelog) are documentation only.
• Lifecycle links go in lifecycle.externalLinks; general docs stay in the operation's own externalLinks.
• Adds a complete OAS 3.3 example.

deprecated takes precedence

• deprecated is the authoritative signal. An operation with lifecycle SHOULD set deprecated: true. If deprecated is absent or false, tools MUST treat the operation as not deprecated and ignore lifecycle: no headers, no deprecation annotations.
• deprecated: true without lifecycle works as before, so APIs can adopt the SAF gradually.

Schema

• The stub schema (properties: {} + additionalProperties: false) rejected every non-empty Lifecycle Object. The new schema validates the Lifecycle, Sunset, and External Documentation Objects, and requires kind in lifecycle.externalLinks.
• Adds 5 pass and 19 fail fixtures; schema branch coverage is 100%.

Open questions for the SIG

• Is lifecycle the right name for the Operation Object field?
• Version: this spec is 1.0.0, but the #5447 example uses lifecycle: 1.1.0.
• Still open: Header Mapping is labelled informative but uses SHOULD; there is no rule that sunset.date >= date; the compatibility [TODO] is unfilled.

Test plan

• oai-spec-test tests/schema — 24 passed, 100% schema coverage
• yarn validate-markdown (not run locally)

[miqui]

@karenetheridge thanks for the review — I switched url to uri-reference in 0c10911 (see the reply on your comment). Could you take another look when you have a chance?

[miqui]

pinning this here for review: OAI/OpenAPI-Specification#5585

[baywet]

it'd be beneficial to also have examples of how those values map to the response headers.

[miqui]

Added in 0371a89: the complete example now shows the Deprecation, Sunset, and Link headers a server would emit for GET /v1/flights, with a table mapping each header to the Lifecycle Object field it comes from. It also notes that the changelog/announcement entries and the Operation Object's own externalLinks generate no headers.

[baywet]

this should probably go under a sub-field named "features" (or something like this) to avoid mutating the schema for the core objects.

so essentially

get:
  features:
    # this is a reserved field name/key for lifecycle
    lifecycle:...

Security would be the only one diverging from this for compat reason.

[handrews]

We need a PR adding the container field to the OpenAPI Object, Path Item Object, and Operation Object (and maybe Response Object? I'm less sure of that so it can be added later). I think it would be great if someone other than me took a shot at this, but if no one is available I will do it.

[miqui]

Agreed. #16 will move lifecycle under the container once the OAS defines it. Until then, 0371a89 adds an editor's note to the spec marking the current lifecycle placement on the Operation Object as provisional, and saying that it will be replaced by the container field.

[baywet]

another thing that came up during the meeting is that we should get generic tooling vendors and get their opinions on the current shape of the spec, especially for scenarios where the lifecycle information and what shows up at runtime disagree.

[miqui]

Thanks @baywet, agreed: vendor input on the current shape would be valuable before this settles. To make it concrete, here are the disagreement scenarios I'd suggest putting to them:

1. Spec says deprecated, runtime doesn't: the operation has deprecated: true and a lifecycle object, but responses carry no Deprecation/Sunset headers. Which should a client or agent trust?
2. Runtime says deprecated, spec doesn't: responses carry Deprecation/Sunset, but the OAD has no lifecycle and/or deprecated is absent. Should tooling surface the runtime signal anyway?
3. Spec and runtime disagree on dates or links: for example, sunset.date in the OAD differs from the Sunset header, or Link relations point to different URLs.
4. lifecycle present but deprecated absent or false: Lifecycle SAF: align with OAS #5447, adopt externalLinks, define schema #16 currently says deprecated takes precedence and lifecycle is ignored. Is that what tools would expect?
5. Inconsistent dates: sunset.date earlier than date. Should this be invalid, or a warning?

For context, the spec currently treats the OAD as the design-time source and the headers as an optional runtime byproduct (see Header Mapping and Relationship to deprecated). It doesn't yet say which side wins when they disagree, apart from the deprecated precedence rule, and point 5 isn't covered at all.

Happy to collect the feedback in a discussion on this repo if that's useful. Are there specific vendors you'd suggest reaching out to?

[handrews]

I haven't gotten through all of this (and I am wondering if we could perhaps break this up to make it easier to resolve pieces and make progress?) but I wanted to publish this before tomorrow's call. My feedback is on details, the direction is good.

[handrews]

I think based on this we need to be explicit that trying to configure a lifecycle object at the other levels is an error. Otherwise it falls into the ambiguous area where things are maybe tolerated but ignored, which is not intuitive.

We do not need to include the history of the decision in the specification. Most readers wont' know what a "SIG discussion" is. I would just document the restriction and the Overlays approach for broader usage.

However, did we consider allowing it at the Path Item Object level? I'm not that familiar with how this will be used, but I have a vague sense that it's common to deprecate/sunset an entire endpoint, which would best be done at a Path Item level. There is also the question of deprecating only specific responses, but I feel like that's a "wait and see if anyone asks for it" thing.

[handrews]

In my view, framing like "Non-goal" is more of a proposal sort of thing. Since this is addressed in detail where usage is described, I would just leave it there. Mentioning it in the introduction without context or crosslink is a bit confusing.

[handrews]

I'd link to the relevant section here and say something like "see OAS section 1.2.3.4 for guidance on using SAFs across multiple OpenAPI Description documents" so that there's no chance of this paragraph drifting from the main section.

[handrews]

I find "complement — not replace" to be a bit vague, but fortunately you have the more precise info available. Based on other text, the Lifecycle Object expands on the meaning of deprecated: true since that is required to be set in order for a Lifecycle Object to be usable.

[handrews]

Let's go ahead and figure this out. Although it is reminding me that the reason I didn't use features for the declarations is that I wanted to use it for the fields... hmmm...

[handrews]

Since these are going into 3.3 and there's no real expectation SAFs would work with an earlier version, I think we can cut this. Otherwise it kind-of implies that there are other versions that work with SAFs but not with this which is a bit confusing.

[handrews]

I see what you're doing here in following how a lot of things in the OAS work. But a lot of those things would not be done the same way now. And many of them are like they are because we had to preserve compatibility. I would recommend:

• A Lifecycle Object MUST result in an error if deprecated: true is not set. (however, if you know of a use case where this would be a problem, that would be a good reason to make this only a SHOULD).

Silently ignoring something is bad UX, and I've seen real production problems from the parts of the OAS that do that.

[handrews]

Does this mean that it's an error to use these relation types in a Link header description on headers fields on a Response Objects associated with operations with a Lifecycle Object? What if the Lifecycle SAF is enabled but there isn't a Lifecycle Object? (I would lean towards them always being an error if lifecycle is enabled- clear errors over ambiguous multiple options).