Breaking Change Detection Prompt for OpenAPI Specs

This prompt is designed for API platform teams, backend engineers, and CI/CD pipeline maintainers who need to automatically detect breaking changes between two versions of an OpenAPI specification. The core job-to-be-done is preventing accidental contract violations from reaching production by surfacing a structured, severity-rated diff before a pull request is merged. The ideal user is an engineering lead or platform architect who understands OpenAPI semantics and needs a reliable, repeatable signal—not a vague summary—to gate a deployment or trigger a manual review. The required context includes the full text of both the old and new OpenAPI specs, and optionally a set of organizational rules (e.g., 'enum value removal is always breaking') to override default heuristics.

Do not use this prompt when you need a human-readable changelog for external developers, when you are reviewing a single spec in isolation without a baseline, or when the change is purely cosmetic (e.g., description text updates). This prompt is also inappropriate for non-OpenAPI contracts like GraphQL schemas or gRPC proto files, which have different breaking change semantics. For high-risk regulated environments, the structured output from this prompt should be treated as a triage aid, not a final verdict; always pair it with a human approval step for changes that touch authentication, payment, or health-data endpoints. The prompt works best when integrated into a CI harness that can cache the previous spec version and feed both into the model as the [OLD_SPEC] and [NEW_SPEC] inputs.

Before wiring this into a production pipeline, validate the prompt against a golden dataset of known breaking and non-breaking changes. Common failure modes include false positives on additive field introductions (which are safe by default) and false negatives on enum value removals (which are always breaking). After reading this section, copy the prompt template, adapt the placeholders to your spec sources, and run it against your last three production spec changes to calibrate severity thresholds before blocking any merges.

The following prompt template is designed to be dropped into your CI pipeline, API governance tool, or review workflow. It accepts two OpenAPI specification versions and a set of configurable constraints, and it returns a structured JSON report classifying each change as breaking, additive, or compatible. Use the square-bracket placeholders to inject your own spec content, output schema requirements, and organizational policies before sending the prompt to the model.

textCopy
You are an API contract reviewer. Your task is to compare two OpenAPI specification versions and produce a structured breaking change analysis.

## INPUTS

### Previous OpenAPI Specification (v1)
[PREVIOUS_SPEC]

### Current OpenAPI Specification (v2)
[CURRENT_SPEC]

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "summary": {
    "breaking_changes_count": <integer>,
    "additive_changes_count": <integer>,
    "compatible_changes_count": <integer>,
    "total_endpoints_affected": <integer>
  },
  "changes": [
    {
      "id": "<string, unique change identifier>",
      "category": "<breaking | additive | compatible>",
      "severity": "<critical | high | medium | low>",
      "change_type": "<e.g., path-removed, parameter-required-added, enum-value-removed, schema-type-changed, response-body-field-removed, field-nullable-changed, operation-deprecated>",
      "location": "<JSON path or endpoint and method, e.g., GET /users/{id} -> response.200.schema.properties.email>",
      "description": "<human-readable explanation of what changed>",
      "before": "<previous value or state>",
      "after": "<current value or state>",
      "affected_clients": ["<list of client types or names if identifiable, otherwise empty array>"],
      "migration_guidance": "<specific fix or upgrade step for consumers>"
    }
  ]
}

## CONSTRAINTS

[CONSTRAINTS]

## CLASSIFICATION RULES

### Breaking Changes (severity: critical or high)
- Removing or renaming a path, operation, or parameter
- Changing a parameter from optional to required
- Removing an enum value from a request or response
- Changing a field type (e.g., string to integer)
- Removing a response body field that was previously present
- Changing a field from nullable to non-nullable
- Adding a new required parameter without a default
- Changing authentication or security scheme requirements
- Removing a supported content type or response code

### Additive Changes (severity: low)
- Adding a new endpoint or operation
- Adding an optional parameter
- Adding a new enum value
- Adding a new response body field
- Adding a new response code
- Adding a new content type

### Compatible Changes (severity: low)
- Description or documentation updates
- Changing a parameter from required to optional
- Adding a default value to a parameter
- Deprecation annotations without removal
- Example updates

## EXAMPLES

[EXAMPLES]

## INSTRUCTIONS

1. Parse both specifications completely before comparing.
2. Compare every path, operation, parameter, request body, response, and schema definition.
3. For each change, assign exactly one category and one severity.
4. If a change affects multiple endpoints, list it once with all affected locations noted.
5. Do not flag cosmetic differences such as whitespace, comment changes, or example value updates as breaking changes.
6. If you are uncertain whether a change is breaking, classify it as breaking with severity medium and note the uncertainty in the description.
7. Return only the JSON object. No additional text, markdown fences, or commentary.

To adapt this template for your environment, replace [PREVIOUS_SPEC] and [CURRENT_SPEC] with the raw YAML or JSON content of your OpenAPI documents. The [CONSTRAINTS] placeholder should contain your organization's specific policies, such as "enum additions to closed enums are breaking" or "deprecation without a sunset header is a medium-severity finding." Use [EXAMPLES] to inject one or two few-shot demonstrations of correct classification, especially for ambiguous cases like field reordering in allOf schemas or discriminator mapping changes. If your pipeline already has a preferred output schema, replace the schema block entirely rather than layering additional fields on top.

Before deploying this prompt into a CI check, run it against a golden dataset of known spec diffs that includes false-positive risks: non-breaking field additions, optional parameter introductions, and description-only changes. Measure precision and recall per change category. If the model flags description updates as breaking or misses enum value removals, add counterexamples to [EXAMPLES] and tighten the classification rules. For production use, always pair this prompt with a JSON schema validator on the output and a human-approval gate for any change classified as critical severity.

This prompt is designed to run as a gate in your CI/CD pipeline, triggered on every pull request that modifies an OpenAPI specification file. The harness should extract the base and head spec versions from the PR (typically the target branch and the feature branch), format them as the [OLD_SPEC] and [NEW_SPEC] inputs, and invoke the model. Because API breaking changes can cause cascading production failures, the harness must treat this as a high-stakes workflow with structured output validation, deterministic retry logic, and a clear human approval path for any detected breaking changes.

Start by implementing a strict output validator that parses the model's JSON response against the expected schema before the CI check reports a result. The validator must confirm that every change entry includes the required fields: location (path and method), change_type (breaking, additive, compatible), severity (critical, high, medium, low), description, and migration_suggestion. If the output fails schema validation, retry once with the same inputs and a stronger constraint instruction appended to the prompt. If the second attempt also fails, fail the CI check with an UNPARSEABLE_OUTPUT status and notify the platform team—do not silently pass. For model choice, use a model with strong structured output capabilities and a context window large enough to hold both full specs; if the specs exceed the context window, preprocess them to include only the paths, schemas, and components that differ between versions rather than truncating arbitrarily.

Wire the validated output into your review workflow. If the model reports zero breaking changes, the CI check can pass automatically. If any breaking change is detected, the CI check should post a structured comment on the PR with the full change list and require an explicit approval from an API platform team member before merge. Log every invocation with the spec versions, model response, validation result, and reviewer action for auditability. Avoid the common failure mode of treating this prompt as a fully automated gate—false negatives on enum value removals and type narrowing are possible, so the harness should always flag breaking changes for human review rather than blocking the PR outright without oversight.