Backward Compatibility Assessment Prompt for API Changes

This prompt is designed for API platform teams, backend engineers, and release managers who need to assess whether proposed API changes break existing consumers. Use it when you have a concrete diff of API schema changes—from OpenAPI, GraphQL, gRPC, or JSON Schema specifications—and need a structured compatibility assessment before cutting a release. The prompt forces the model to reason about field additions, removals, type changes, enum modifications, and default value shifts, then produce a compatibility matrix with severity ratings and migration guidance. The core job-to-be-done is preventing production incidents where a schema change silently breaks downstream clients, mobile apps, or internal services that depend on your API contract.

The ideal user has access to a version-controlled API specification and a diff between the current and proposed versions. You should provide the full schema context, not just the changed lines, because the model needs to understand field relationships, required constraints, and nested object structures to accurately assess impact. The prompt works best when you include consumer information—such as which endpoints are actively used, which client versions are in the field, and any telemetry on field usage patterns. Without this context, the model can identify technical breaking changes but cannot prioritize by actual consumer impact. For high-risk APIs in regulated domains, always route the output through human review before accepting the compatibility verdict.

Do not use this prompt when you lack a concrete schema diff or when the change is purely internal with no consumer-facing contract exposure. It is not a substitute for integration tests, contract testing frameworks, or canary deployment analysis. The prompt assesses structural compatibility, not behavioral compatibility—a field type change from integer to string is detectable, but a subtle change in business logic that returns different values for the same input is not. If your API uses semantic versioning, pair this prompt with a version bump recommendation workflow. After running the assessment, validate the output against your own breaking change policy, and use the migration guidance as a starting point for your actual migration documentation, not as the final published guide.

This prompt template is the core engine for a backward compatibility assessment. It is designed to be executed by an AI coding agent or an automated pipeline step that has access to your API's schema definitions and the proposed code diff. The template uses square-bracket placeholders for all dynamic inputs, ensuring a clean separation between the instruction set and the data. Before using this prompt, you must have already gathered the relevant OpenAPI/Swagger specs, protobuf definitions, or interface files, and generated a focused diff of the changes.

markdownCopy
You are a principal API architect specializing in backward compatibility. Your task is to analyze a proposed API change and produce a structured compatibility assessment.

## Input Data
- **API Contract Diff:**
```diff
[API_DIFF]

• Full Current API Schema (for context):

yamlCopy
[CURRENT_SCHEMA]

• Consumer Impact Context: [CONSUMER_CONTEXT]

Task

1. Classify every change in the diff as BREAKING, NON-BREAKING, or CLARIFICATION.
2. For each BREAKING change, determine the severity (CRITICAL, HIGH, MEDIUM, LOW) based on the likelihood and impact of client failure.
3. Identify all affected endpoints and fields.
4. Simulate a consumer's request/response flow before and after the change to illustrate the break.
5. Propose a migration path for consumers, including a code snippet if applicable.
6. Enumerate edge cases where the change could cause silent data corruption or unexpected errors.

Output Schema

You must respond with a single JSON object matching this exact structure: { "assessment_summary": { "total_changes": <number>, "breaking_changes": <number>, "overall_risk": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" }, "changes": [ { "change_id": "<unique-slug>", "type": "BREAKING" | "NON-BREAKING" | "CLARIFICATION", "severity": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | null, "affected_elements": ["<endpoint/path>", "<field_name>"], "description": "<plain-english description of the change>", "consumer_simulation": { "before": "<example request/response before the change>", "after": "<example request/response after the change, showing the error or altered behavior>" }, "migration_path": { "steps": ["<actionable step for the consumer>"], "code_snippet_before": "<optional code example before migration>", "code_snippet_after": "<optional code example after migration>" }, "edge_cases": ["<description of a potential silent failure or edge case>"] } ] }

Constraints

• Ground every finding in the provided diff and schema. Do not invent changes.
• If a field is marked as deprecated but still present, it is a NON-BREAKING change with a note.
• A new required field is a CRITICAL breaking change.
• Changing a field's type (e.g., string to integer) is a CRITICAL breaking change.
• If the diff is empty or contains no API-relevant changes, return an empty changes array and an overall_risk of "LOW".

To adapt this template, replace the placeholders with data from your CI/CD pipeline or local environment. [API_DIFF] should be a unified diff of the proposed schema changes. [CURRENT_SCHEMA] is the full, raw text of the existing API contract. [CONSUMER_CONTEXT] is a critical, often-overlooked field where you should inject known information about how clients use the API—for example, 'Mobile clients cache this field aggressively' or 'This endpoint is only used by an internal admin tool.' This context dramatically improves the severity assessment. After running the prompt, always validate the output JSON against the schema before passing it to a downstream release notes generator or approval dashboard.

This prompt is designed to be a gating step in a CI/CD pipeline, running automatically whenever an API specification change is proposed. The ideal integration point is a pull request check that executes after the OpenAPI/Swagger diff is generated but before the change is merged. The prompt consumes a structured diff of the API contract—typically the output of a tool like openapi-diff or a custom JSON comparison script—and produces a compatibility matrix. This matrix should be stored as a pipeline artifact and attached to the PR as a comment or status check, blocking the merge if breaking changes are detected without explicit approval.

To implement, wrap the prompt in a script that first generates the API diff artifact. The script should then call the LLM with the prompt template, injecting the diff into the [API_DIFF] placeholder and the current API version into [CURRENT_VERSION]. The model's response must be validated against a strict JSON schema before the pipeline proceeds. A critical validation step is to ensure that every endpoint listed in the output's affected_endpoints array actually exists in the diff input, preventing hallucinated endpoints. If the severity field for any change is breaking, the pipeline should automatically fail and require a human approval override. For non-breaking changes, the output can be used to auto-populate a migration guide draft in the repository's documentation.

For model choice, a model with strong structured output capabilities and a large context window is required, as API diffs can be verbose. Use a low temperature setting (0.0–0.1) to ensure deterministic, repeatable assessments. Implement a retry loop with a maximum of three attempts if the output fails JSON schema validation. On the second and third retries, append the validation error to the prompt's [CONSTRAINTS] section to guide the model toward a valid structure. Log every assessment, including the raw diff, the model's full response, and the validation result, to an audit trail for release governance. Avoid running this prompt on every commit; trigger it only on pull requests that modify files in designated API specification directories to control cost and noise.