# Ship a breaking change without breaking anyone

Source: https://api-genie.dev/blog/ship-a-breaking-change-without-breaking-anyone

A pull request on the Carpet Express API renames the shipment's `reference` to
`merchantReference`, in each request and response that carries a shipment, and drops the legacy
`GET /rates/legacy`. Both changes are right. Both break the clients that exist today, and
`apigenie diff` says so:

```text
$ apigenie diff carpet-express.openapi.yaml pr/carpet-express.openapi.yaml
pr/carpet-express.openapi.yaml
   866  7      breaking  Removed operation GET /rates/legacy
  1279  7      breaking  Modified operation GET /jobs/{jobId}
  1279  7      breaking  Modified response code 200
   841  7  non-breaking  Modified operation POST /rates
   841  7  non-breaking  Request body changed
   133  7      breaking  Modified operation GET /shipments
   133  7      breaking  Modified response code 200
   218  7      breaking  Modified operation POST /shipments
   218  7      breaking  Request body changed
   218  7      breaking  Modified response code 201
   218  7      breaking  Modified response code 202
   318  7      breaking  Modified operation POST /shipments/imports
   318  7      breaking  Modified response code 202
   301  7      breaking  Modified operation POST /shipments/search
   301  7      breaking  Modified response code 200
   418  7      breaking  Modified operation GET /shipments/{shipmentId}
   418  7      breaking  Modified response code 200
   457  7      breaking  Modified operation PATCH /shipments/{shipmentId}
   457  7      breaking  Request body changed
   457  7      breaking  Modified response code 200
$ echo $?
1
```

The usual answers are "bump the major version" (and run two APIs for a year) or "just do it" (and
answer the support tickets). There is a third answer that database people have used for decades
and API people rarely do, because it is tedious by hand: expand, then contract.
`apigenie evolve plan` does the tedious part. It is experimental in 0.10.0, which means its options
and the layout of its plan can still change in a minor release.

## Expand and contract, once

1. **Expand.** Add the new shape next to the old one. Mark the old one deprecated with a sunset
   date. Nothing breaks: every old client still works, every new client can move.
2. **Window.** Consumers migrate. The server emits both, accepts both.
3. **Contract.** On or after the sunset date, remove the old shape.

The reason teams don't do this is not that they disagree with it. It is that step 1 means
hand-editing the spec into a third document that is neither the old one nor the new one, getting
each `deprecated: true`, each `x-sunset`, each "now optional, later required" right, and then
convincing yourself it really is non-breaking.

## Plan the change

Give it the document consumers use today and the document the pull request arrives at:

```text
$ apigenie evolve plan carpet-express.openapi.yaml pr/carpet-express.openapi.yaml --window 90d --out evolve-out
apigenie evolve plan (experimental, outside the 1.0 compatibility promise)
Evolution of carpet-express.openapi.yaml to pr/carpet-express.openapi.yaml (today 2026-10-29, window 90d)

expand wave (version 2.5.0): ship now
  remove-operation-quoteRateLegacy  [remove-operation] deprecate GET /rates/legacy; sunset 2027-01-27
  rename-request-property-FreightShipment-allOf-0-reference  [rename-request-property] keep /components/schemas/FreightShipment/allOf/0/properties/reference (deprecated) next to /components/schemas/FreightShipment/allOf/0/properties/merchantReference; sunset 2027-01-27
  rename-request-property-Job-result-oneOf-1-oneOf-0-allOf-1-parcels-items-reference  [rename-request-property] keep /components/schemas/Job/properties/result/oneOf/1/oneOf/0/allOf/1/properties/parcels/items/properties/reference (deprecated) next to /components/schemas/Job/properties/result/oneOf/1/oneOf/0/allOf/1/properties/parcels/items/properties/merchantReference; sunset 2027-01-27

contract wave (version 2.6.0): not before 2027-01-27
  remove-operation-quoteRateLegacy  remove GET /rates/legacy
  rename-request-property-FreightShipment-allOf-0-reference  remove /components/schemas/FreightShipment/allOf/0/properties/reference
  rename-request-property-Job-result-oneOf-1-oneOf-0-allOf-1-parcels-items-reference  remove /components/schemas/Job/properties/result/oneOf/1/oneOf/0/allOf/1/properties/parcels/items/properties/reference

Server checklist:
  - accept both reference and merchantReference until 2027-01-27 (rename-request-property-FreightShipment-allOf-0-reference)
  - accept both reference and merchantReference until 2027-01-27 (rename-request-property-Job-result-oneOf-1-oneOf-0-allOf-1-parcels-items-reference)

Checks:
  expand-non-breaking: ok
  contract-scheduled-only: ok
  contract-equals-target: ok

Written:
  evolve-out/plan.yaml
  evolve-out/1-expand.yaml
  evolve-out/2-contract.yaml
```

Twenty breaking lines became three units: the removed operation, and the renamed property seen
through the two schemas that carry it (the unit is named after the first place the differ reported
the property; `sites` in `plan.yaml` lists the others). Three files land in `evolve-out/`:

| File | What it is | When to ship it |
| --- | --- | --- |
| `1-expand.yaml` | The target document with each old element kept next to its replacement, `deprecated: true` and `x-sunset` | now |
| `2-contract.yaml` | The target document | on or after the sunset date |
| `plan.yaml` | The waves, the units, the residue, the server notes | |

In the expand wave, the old property sits next to the new one with its sunset:

```yaml
        reference:
          type: string
          description: Your order or delivery number.
          maxLength: 64
          deprecated: true
          x-sunset: 2027-01-27
```

## How it knew it was a rename

The differ sees a removed property and an added one. The planner pairs them when the removed and
the added member have the same schema after following `$ref`s and ignoring descriptions and
examples; `plan.yaml` records the pairing with `detected: true`. For `reference` and
`merchantReference` (both `string`, `maxLength: 64`) that is enough. When it isn't, you tell it:

```yaml
# hints.yaml
renames:
  - from: /components/schemas/ShipmentCommon/properties/reference
    to: /components/schemas/ShipmentCommon/properties/merchantReference
window: 12w
reason: Align field names with the merchant portal
```

```text
$ apigenie evolve plan carpet-express.openapi.yaml pr/carpet-express.openapi.yaml --hints hints.yaml --out evolve-out
apigenie evolve plan (experimental, outside the 1.0 compatibility promise)
Evolution of carpet-express.openapi.yaml to pr/carpet-express.openapi.yaml (today 2026-10-29, window 12w)

expand wave (version 2.5.0): ship now
  remove-operation-quoteRateLegacy  [remove-operation] deprecate GET /rates/legacy; sunset 2027-01-21
      reason: Align field names with the merchant portal
```

The reason travels into the plan and the report, so the person who reads `plan.yaml` in February
knows why the field moved.

## The recipes, and what has none

Each breaking change becomes a unit with a recipe, and the recipes are the moves a careful API
owner makes by hand: an operation that goes stays deprecated with its sunset, then is removed; a
renamed property keeps both names, then loses the old one; a request property that becomes
required is optional first. The [reference](/docs/reference/cli/evolve) lists them.

Some breaking changes have no safe recipe: a changed type or format, a new security requirement,
a replaced server. Those are residue. Change `transitDays` from an integer to a string in the
same pull request, and the plan says so instead of pretending:

```text
$ apigenie evolve plan carpet-express.openapi.yaml pr/residue.yaml --window 90d --out evolve-residue
apigenie evolve plan (experimental, outside the 1.0 compatibility promise)
Evolution of carpet-express.openapi.yaml to pr/residue.yaml (today 2026-10-29, window 90d)

expand wave (version 2.5.0): ship now

contract wave (version 3.0.0): not before 2027-01-27

Residue (needs a major version or a new resource):
  residue-1  Added schema.type[0] at /components/schemas/Rate/properties/transitDays/type/0
      a changed type or format has no parallel shape; add a property with the new type next to the old one
  residue-2  Removed schema.format at /components/schemas/Rate/properties/transitDays/format
      a changed type or format has no parallel shape; add a property with the new type next to the old one
$ echo $?
1
```

The files are still written, the contract wave becomes a major version, and the exit status is 1
until the residue is handled: a new property with the new type next to the old one, or a new
resource.

## Proved, not promised

Before anything is written, the planner runs `diff` three times, with your configuration, and
reports the checks you saw above. You can run the proof yourself at any time, which is the point
of writing the waves as plain documents:

```text
$ apigenie diff carpet-express.openapi.yaml evolve-out/1-expand.yaml
evolve-out/1-expand.yaml
  1352  7    non-breaking  Modified operation GET /jobs/{jobId}
  1352  7    non-breaking  Modified response code 200
   887  7    non-breaking  Modified operation POST /rates
   887  7    non-breaking  Request body changed
  1453  7  non-functional  Modified operation GET /rates/legacy
   119  7    non-breaking  Modified operation GET /shipments
   119  7    non-breaking  Modified response code 200
   209  7    non-breaking  Modified operation POST /shipments
   209  7    non-breaking  Request body changed
   209  7    non-breaking  Modified response code 201
   209  7    non-breaking  Modified response code 202
   321  7    non-breaking  Modified operation POST /shipments/imports
   321  7    non-breaking  Modified response code 202
   303  7    non-breaking  Modified operation POST /shipments/search
   303  7    non-breaking  Modified response code 200
   436  7    non-breaking  Modified operation GET /shipments/{shipmentId}
   436  7    non-breaking  Modified response code 200
   480  7    non-breaking  Modified operation PATCH /shipments/{shipmentId}
   480  7    non-breaking  Request body changed
   480  7    non-breaking  Modified response code 200
$ echo $?
0
```

The same twenty lines, each one non-breaking. The contract wave is breaking today and
non-breaking once the sunset has passed, because `diff` knows the sunset dates:

```text
$ apigenie diff evolve-out/1-expand.yaml evolve-out/2-contract.yaml | head -n 2
evolve-out/2-contract.yaml
  1453  7      breaking  Removed operation GET /rates/legacy
$ apigenie diff evolve-out/1-expand.yaml evolve-out/2-contract.yaml --today 2027-01-27 | head -n 2
evolve-out/2-contract.yaml
  1453  7  non-breaking  Removed operation GET /rates/legacy
```

A CI job with `--today` is the calendar entry that says when `2-contract.yaml` may ship.

## The server checklist

A document can say that both `reference` and `merchantReference` exist. Only the implementation
can emit both. Each unit that needs it carries a server note, and the report prints them as a
checklist. Put the checklist in the ticket. A plan whose server doesn't follow its notes is a lie
the documents can't catch.

## What it does not do

The recipes cover OpenAPI documents; AsyncAPI, GraphQL and Protobuf have no planner yet. The plan
is written once and not tracked: there is no command that tells you, in January, which units are
past their sunset. And a change with residue is still yours to design. What it does is the part
nobody did: write the intermediate document, and prove it.

## Try it

```sh
curl -sSL https://api-genie.dev/examples/carpet-express.tar.gz | tar xz
cd carpet-express
apigenie evolve plan carpet-express.openapi.yaml pr/carpet-express.openapi.yaml --window 90d --out evolve-out
cat evolve-out/plan.yaml
```

Next week, the contract meets the traffic:
[The traffic you already have is the contract test](/blog/the-traffic-you-already-have-is-the-contract-test).
