Worked-example report v1 / Delimit team / 2026-07-12

Generating an API migration guide from breaking changes

The merge gate writes the upgrade steps, from the diff.

Delimit ran over two Box OpenAPI schema changes (commit range 98a1ca0 to 177e92d): a legal-hold assignment schema restructured and an AI-agent reference field made required. Four breaking changes, classified major, turned into a step-by-step migration guide.

4 breaking · 3 additive

Why a worked example. Box maintains its API definition as a public OpenAPI document, so two real schema-breaking changes make a clean, small subject for the migration-guide generator.

box/box-openapi is public; the two commits are real.
This is not a defect report and Box is not a Delimit customer. The schema changes are intentional; we use the diff only to show the generated guide.
Reproducible byte-for-byte (command at the end).

The problem

The migration guide is the document nobody wants to write and every consumer needs. When a breaking change ships, someone has to translate "the schema changed" into "here is exactly what your code must do differently." Written by hand, that guide lags the change, misses cases, and drifts from the spec. Written by an AI assistant from a prose description of the change, it can invent steps that were never in the diff.

The merge gate generates the guide from the classified diff itself. Every step maps to a change the gate actually found, so the guide cannot describe a break that is not there or omit one that is.

The setup

The same gate that fails the check on a breaking change also emits the migration guide for the breaks it found. One CI job on every pull request that touches the spec.

# .github/workflows/api-merge-gate.yml
name: API merge gate
on: [pull_request]

jobs:
  delimit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: delimit-ai/delimit-action@v1
        with:
          spec: openapi.json

What free Delimit detects

Four breaking changes across two schemas, plus the additive remainder. Each finding is the input to one migration step.

breakingfinding F1
change type: composition_member_removed
surface: #/components/schemas/LegalHoldPolicyAssignedItem
Three oneOf members were removed from the legal-hold assignment schema. A request that sent one of the now-removed variant shapes no longer validates. This is breaking for clients that construct the request body from the old set of allowed shapes.
breakingfinding F2
change type: required_field_added
surface: #/components/schemas/LegalHoldPolicyAssignedItem.id
A new required field id was added to the same schema. Requests built against the prior shape, which did not send id, now fail validation until the field is supplied.
breakingfinding F3
change type: required_field_added
surface: #/components/schemas/LegalHoldPolicyAssignedItem.type
A new required field type was added alongside id. Both must now be present on the assignment object, so the legal-hold restructure is a two-part change to the request contract.
breakingfinding F4
change type: required_field_added
surface: #/components/schemas/AiAgentReference.id
On a second schema, the AI-agent reference object, the id field changed from optional to required. Any caller that referenced an agent without an explicit id now sends an invalid body.
additivefinding A1
change type: optional_field_added (3)
surface: multiple schemas
The rest of the window is additive: three new optional fields, safe for existing clients. Seven changes total, four breaking, three additive. A small, surgical window, which is what makes the generated guide easy to read end to end.

The migration guide the gate generates

Verbatim generated output for this diff, one step per breaking change:

# Migration Guide: API (2024.0 -> 2024.0)

This release contains 4 breaking change(s).
Follow the steps below to update your integration.

### Step 1: Composition Member Removed
Change:   3 oneOf member(s) removed at
          LegalHoldPolicyAssignedItem (breaking for
          request clients)
Location: LegalHoldPolicyAssignedItem.oneOf
Action:   Review the change and update your integration
          accordingly.

### Step 2: Required Field Added
Change:   New required field 'id' added at
          LegalHoldPolicyAssignedItem
Location: LegalHoldPolicyAssignedItem.id
Action:   If this is a request body field, include it in
          all requests. If this is a response field, update
          parsers to handle the new field.

### Step 3: Required Field Added
Change:   New required field 'type' added at
          LegalHoldPolicyAssignedItem
Location: LegalHoldPolicyAssignedItem.type
Action:   Include it in all requests.

### Step 4: Required Field Added
Change:   Field 'id' changed from optional to required at
          AiAgentReference
Location: AiAgentReference.id
Action:   Always supply id when referencing an agent.

Both source specs advertise version 2024.0, so the guide header shows an unchanged string on a major-class change set. Four breaks in, four steps out, each keyed to a JSON Pointer in the spec.

Why a hand- or prompt-written guide drifts

A guide written from a human summary of "we tightened the legal-hold schema" will probably mention the new required fields and probably forget that three oneOf members were also removed. A guide a model writes from the pull-request description inherits whatever that description left out, and may add plausible steps that never happened. Both are downstream of prose, not of the diff.

The gate's guide is downstream of the classified change set. It has exactly as many steps as there are breaking changes, no more and no fewer, each tied to the pointer where the change occurred.

Reproduce locally

# Install the CLI
npm install -g delimit-cli

# Clone the spec repo
git clone https://github.com/box/box-openapi
cd box-openapi

# Extract the two versions across the schema changes
git show 98a1ca0:openapi.json > /tmp/old.json
git show 177e92d:openapi.json > /tmp/new.json

# Run the merge gate (emits the migration guide for the breaks)
delimit lint /tmp/old.json /tmp/new.json

If your bytes differ from this report, raise it on the Delimit repo.

Free detects. Pro proves.

Free Delimit is the merge gate: it detects the breaking changes and generates the migration guide on every pull request. Install delimit-cli or add the delimit-ai/delimit-action to CI. Free for individual maintainers.

Pro binds the guide to a signed, replayable attestation: the migration guide and the classified change set it came from, packaged as a portable record a reviewer or downstream consumer can verify without rerunning the gate. Pro tier $10/month for teams.