{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to review API design for backward compatibility risks","description":"How to prompt an LLM to compare two OpenAPI versions for breaking changes, where human judgment ends, and how Redocly CLI plus Respect keep spec and live behavior aligned in CI.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-review-api-design-for-backward-compatibility-risks","__idx":0},"children":["Use AI to review API design for backward compatibility risks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your public OpenAPI file is a promise to every client that already shipped. When a field disappears, a type tightens, or a path renames, the break often shows up first in someone else’s production log. A large language model can read two snapshots and narrate what changed. It is not a contract test. Pair that review with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/api-standards"},"children":["API standards and governance"]}," in CI using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]},", then let ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/respect/"},"children":["Redocly Respect"]}," exercise critical workflows against a real server."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This article covers what counts as breaking, how to prompt with two spec versions, and how CLI linting plus Respect’s Arazzo-aware runs complement AI judgment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-compatibility-risk-hides-in-large-specs","__idx":1},"children":["Why compatibility risk hides in large specs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Breaking changes are not always obvious renames. Optional can become required, enums can lose values clients still send, or a response schema can drop a field your SDK exposed. Line-by-line YAML diffs fatigue humans fast. A model can hold both trees and highlight operations where caller behavior likely changed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The model may still hallucinate a reorder as a semantic change, or miss runtime behavior the spec never captured. Treat it as a reviewer that returns a prioritized list, and treat CI as the judge that fails the merge until the list is addressed or ruled out."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-counts-as-breaking-for-clients","__idx":2},"children":["What counts as breaking for clients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Agree with consumers what “breaking” means before you prompt: removed paths, renamed fields, stricter types, new required properties, changed status semantics, narrower enums. Additive changes still belong in a changelog but need not fail the gate."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Have the model label each finding breaking, probably safe, or needs human decision. If some branches are additive-only, say that so new optional fields are not flagged as breaks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-to-prompt-ai-with-two-openapi-versions","__idx":3},"children":["How to prompt AI with two OpenAPI versions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"context-block-template","__idx":4},"children":["Context block template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste something shaped like this before the two files:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are comparing two OpenAPI 3.1 documents for backward compatibility.\n\nRoles:\n- Document A: last published spec (tag v1.2.0).\n- Document B: candidate release on branch release/1.3.\n\nConsumer contract (plain language):\n- Mobile clients cache GET /users/{id} for 24 hours; removing any 200 response field they deserialize is breaking.\n- Webhooks must accept unknown JSON keys on callbacks.\n\nTasks:\n1. List operations where request or response schemas narrowed for existing clients.\n2. List renamed or removed paths, parameters, and schema properties with JSON pointers when possible.\n3. Flag changes to error models that might alter client branching on status plus body shape.\n4. Output a table: change, breaking Y/N/uncertain, suggested mitigation (deprecation header, versioned path, dual-write period).\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste both files with clear delimiters. If policy lives only in Slack, summarize it in the prompt instead of assuming the model knows your release train."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"review-checklist-for-the-model","__idx":5},"children":["Review checklist for the model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cover default responses, shared components reused across tags, and discriminator or oneOf shapes where a variant disappeared. Require operationIds on each row so tickets map to generators and tests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"where-redocly-cli-takes-over","__idx":6},"children":["Where Redocly CLI takes over"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["AI output is not policy until it becomes rules and CI. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," applies the same ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["built-in rules"]}," and custom rules on every commit, so repeated enum removals fail the build instead of reappearing in chat."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/guides/configure-rules"},"children":["guide to configuring a ruleset"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended-strict"]}," as baseline, then encode your compatibility policy explicitly. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/lint"},"children":["lint command"]}," also validates ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/arazzo/what-is-arazzo"},"children":["What is Arazzo?"]}," files next to your OpenAPI roots."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/configuration/apis"},"children":["Per-API configuration"]}," lets a public bundle stay stricter than an internal experimental service, similar to telling the model to ignore internal-only paths."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"where-respect-takes-over","__idx":7},"children":["Where Respect takes over"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specs can parse yet still misdescribe production. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/respect/"},"children":["Redocly Respect"]}," sends real requests and checks responses against OpenAPI and Arazzo expectations. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/respect/use-cases"},"children":["use cases for Respect"]}," include local runs, PR CI, and scheduled smoke tests against staging or production."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Model the journeys that define compatibility: login then profile, create then poll, cancel then verify. When the server diverges from the description, Respect fails where a static diff would stay green. Use AI to summarize failure logs for humans, not to skip the run."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-ai-cannot-prove","__idx":8},"children":["What AI cannot prove"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A model cannot prove every client tolerates a change. It does not execute your stack or know compensating behavior inside mobile apps. It should not be the only gate when SLAs attach to specific response shapes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use AI to widen spec review, Respect to bind descriptions to deployed behavior, and humans for intentional breaks with explicit version bumps."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":9},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always pass two concrete artifacts, for example bundled YAML from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["main"]}," and from your release branch, not a vague “what changed lately” question."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask for JSON pointers or operationIds so tickets map cleanly to engineering work."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Encode repeated AI findings as rules so the same mistake cannot return unnoticed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep Arazzo workflows short and focused on compatibility-critical paths so CI stays fast and failures are interpretable."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-approach-cannot-replace","__idx":10},"children":["What this approach cannot replace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach cannot replace consumer-driven contract tests owned by client teams, canary analysis, or database migration review when behavior shifts outside HTTP. It is a structured spec review plus deterministic tooling, not a full release certification."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-the-pieces-fit-together","__idx":11},"children":["How the pieces fit together"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n A[OpenAPI A plus OpenAPI B] --> B[LLM compatibility review]\n B --> C[Human updates spec and rules]\n C --> D[Redocly CLI lint]\n D --> E[Respect Arazzo runs]\n E --> F[CI or scheduled gate]\n","diagramHtml":"

OpenAPI A plus OpenAPI B

LLM compatibility review

Human updates spec and rules

Redocly CLI lint

Respect Arazzo runs

CI or scheduled gate

","diagramHtmlDark":"

OpenAPI A plus OpenAPI B

LLM compatibility review

Human updates spec and rules

Redocly CLI lint

Respect Arazzo runs

CI or scheduled gate

"},"children":["graph LR\n A[OpenAPI A plus OpenAPI B] --> B[LLM compatibility review]\n B --> C[Human updates spec and rules]\n C --> D[Redocly CLI lint]\n D --> E[Respect Arazzo runs]\n E --> F[CI or scheduled gate]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["AI widens the diff narrative. Redocly CLI enforces the spec text. Respect checks that the running API still honors the workflows your clients depend on."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":12},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/api-standards"},"children":["API standards and governance"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["built-in rules"]},", and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/lint"},"children":["lint command"]}," on every change."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/respect/"},"children":["Redocly Respect"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/respect/use-cases"},"children":["use cases for Respect"]}," when you need PR or scheduled runs that still fail if the live API drifts while the YAML stays valid."]}]},"headings":[{"value":"Use AI to review API design for backward compatibility risks","id":"use-ai-to-review-api-design-for-backward-compatibility-risks","depth":1},{"value":"Why compatibility risk hides in large specs","id":"why-compatibility-risk-hides-in-large-specs","depth":2},{"value":"What counts as breaking for clients","id":"what-counts-as-breaking-for-clients","depth":2},{"value":"How to prompt AI with two OpenAPI versions","id":"how-to-prompt-ai-with-two-openapi-versions","depth":2},{"value":"Context block template","id":"context-block-template","depth":3},{"value":"Review checklist for the model","id":"review-checklist-for-the-model","depth":3},{"value":"Where Redocly CLI takes over","id":"where-redocly-cli-takes-over","depth":2},{"value":"Where Respect takes over","id":"where-respect-takes-over","depth":2},{"value":"What AI cannot prove","id":"what-ai-cannot-prove","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What this approach cannot replace","id":"what-this-approach-cannot-replace","depth":2},{"value":"How the pieces fit together","id":"how-the-pieces-fit-together","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to review API design for backward compatibility risks","description":"How to prompt an LLM to compare two OpenAPI versions for breaking changes, where human judgment ends, and how Redocly CLI plus Respect keep spec and live behavior aligned in CI."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-api-design-backward-compatibility-risks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}