OpenAPI Deprecation Field Annotation Prompt Template

This prompt is designed for API governance teams, platform engineers, and technical product managers who need to systematically add deprecation metadata to existing OpenAPI specifications. The core job-to-be-done is transforming a spec that has unannotated deprecated endpoints into one where every deprecated path, operation, or schema property carries a complete set of machine-readable and human-readable deprecation fields. This includes deprecated: true, x-sunset dates, migration guide URLs, and replacement operation IDs. The reader is expected to have an existing OpenAPI 3.0 or 3.1 specification and a deprecation policy that defines sunset timelines, replacement endpoints, and communication standards.

Use this prompt when you have a batch of operations or schemas that need consistent deprecation annotation and you want to enforce a uniform structure across your API surface. It is particularly valuable during API version cleanup sprints, pre-release governance reviews, or when onboarding legacy APIs into a centralized developer portal. The prompt expects structured inputs: the target spec fragment, a deprecation policy document, and a mapping of deprecated surfaces to their replacements. Do not use this prompt for greenfield API design, for generating net-new deprecation policies from scratch, or for deciding whether an endpoint should be deprecated—it assumes the deprecation decision has already been made and only needs to be documented correctly.

Before running this prompt, ensure you have a validated OpenAPI spec, a clear sunset calendar, and a documented replacement for every surface being deprecated. The harness described in the implementation section will reject annotations that lack a replacement reference or a sunset date, so incomplete inputs will produce validation errors rather than partial output. If your team has not yet identified replacements for deprecated endpoints, start with an API inventory audit before applying this prompt. The output is a spec patch or a fully annotated spec fragment ready for review, not a final publication artifact—always run the conformance checks and human review steps before merging into your published spec.

This prompt template is designed to be integrated into an API governance pipeline. It takes an existing OpenAPI specification and a set of deprecation rules as input, and it produces an annotated specification where every deprecated surface—paths, operations, and schemas—is clearly marked with structured metadata. The template uses square-bracket placeholders for all dynamic inputs, making it straightforward to adapt for different API surfaces and organizational policies.

textCopy
You are an API governance assistant. Your task is to annotate an OpenAPI specification with deprecation metadata.

## INPUT
- OpenAPI Specification: [OPENAPI_SPEC]
- Deprecation Policy: [DEPRECATION_POLICY]
- Current Date: [CURRENT_DATE]

## CONSTRAINTS
- Do not modify any existing schema, path, or operation logic.
- Only add or update the `deprecated` field and `x-sunset` extension properties.
- Every deprecated operation or schema MUST have a documented alternative.
- If no alternative exists, flag the item for human review instead of marking it deprecated.
- Use the exact sunset date format: YYYY-MM-DD.
- Migration links must be absolute URLs or valid internal operationId references.

## OUTPUT_SCHEMA
Return a JSON object with two keys:
1. `annotated_spec`: The complete OpenAPI specification with deprecation annotations applied.
2. `review_required`: An array of objects for items that require human review, each with:
   - `location`: The JSON path to the item (e.g., "paths./users.get")
   - `reason`: Why it could not be automatically deprecated
   - `recommendation`: Suggested next steps

## DEPRECATION ANNOTATION RULES
For each path, operation, or schema property that matches the deprecation policy:
1. Set `deprecated: true`.
2. Add an `x-sunset` object with:
   - `sunset-date`: [SUNSET_DATE] or a calculated date based on the policy
   - `replacement`: The operationId or URL of the replacement
   - `migration-guide`: A link to the migration documentation
   - `deprecation-notice`: A human-readable explanation
3. If the item is a schema property, also add `x-sunset` to the parent schema's description if not already present.

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

To adapt this template, replace the placeholders with concrete values for your workflow. [OPENAPI_SPEC] should be the raw YAML or JSON of your specification. [DEPRECATION_POLICY] defines the rules for what gets deprecated—this could be a list of operation IDs, a date threshold, or a reference to an external policy document. [EXAMPLES] should include one or two few-shot examples showing a path or schema before and after annotation. For high-stakes APIs, set [RISK_LEVEL] to high and ensure the output is routed through a human review queue before the annotated spec is published. The review_required array in the output schema is your safety net: it captures items the model could not confidently annotate, preventing silent failures in production.

This prompt is designed to be called programmatically as part of a spec governance workflow, not as a one-off chat interaction. The typical integration point is a CI/CD pipeline or an internal API governance service that processes OpenAPI specs before they are published to a developer portal or gateway. The harness should extract the target spec, identify operations and schemas that already carry a deprecated: true flag, and pass each deprecated surface to the prompt along with the full spec context so the model can locate replacement operations and suggest accurate migration links. Because the prompt modifies a machine-readable specification that downstream tools consume, every output must pass structural validation before it is merged back into the spec.

The implementation should follow a validate-before-merge pattern. After the model returns annotated paths, operations, or schemas, run the output through an OpenAPI structural validator (such as Redocly CLI, Spectral, or a custom JSON Schema validator) to confirm that no required fields were dropped and that all $ref targets remain intact. Next, apply a deprecation-specific linting rule: every surface marked deprecated: true must have a non-empty x-sunset-date (or equivalent extension), a x-migration-guide URL, and either a x-replacement-operationId or a documented reason why no replacement exists. If the model output fails these checks, retry once with the validation errors injected into the prompt as additional [CONSTRAINTS]. If the retry also fails, route the spec to a human reviewer through a pull request comment or a governance dashboard ticket. Do not silently merge incomplete deprecation annotations—downstream consumers rely on this metadata to plan their migrations.

For model selection, prefer a model with strong structured output support and a large context window, since the prompt requires the full spec as input. GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are suitable choices. Enable structured output mode (JSON mode or function calling with a strict schema) to enforce the expected annotation format. Log every invocation with the spec version, the list of deprecated surfaces passed in, the model's raw output, validation results, and whether the output was auto-merged or escalated. This audit trail is essential for governance reviews and for debugging cases where the model hallucinates replacement operation IDs or invents sunset dates. Finally, version the prompt template itself in your prompt registry and pin model versions in production to avoid silent behavior changes when providers update their models.