Versioning

Two things version independently here, and conflating them breaks callers.

Axis	Looks like	Moves when
API contract	`/grapes/v1/`	Only on a breaking change. A new version does not retire the old for at least 12 months.
Dataset version	`wikidata-varieties-2026.1`	The upstream data or the build that shapes it changes. Carried on every response as `datasetVersions`.

Wikidata is edited continuously, so dataset values move on every refresh. That is data moving, not contract breaking: the shape is stable, and every response carries datasetVersions so you can pin and compare.

The test that settles arguments

Could a correct client, written against the current contract and not changed, now break or silently misread a response? If yes it is breaking. If you have to reason about whether a client should have depended on something, it is breaking — callers depend on what you shipped, not on what you meant.

Breaking

Removing or renaming a response field; changing its type or units.
Removing an endpoint or changing its path.
Adding a required request parameter, or tightening validation.
Changing a default, page size or sort order.
Changing the shape of a record inside a published dataset.
Changing the meaning of the colour vocabulary — a caller branching on colour depends on those five values meaning what they meant.

Additive

Adding an endpoint, a response field, or an optional parameter.
Widening validation.
Correcting data, or rebuilding from a newer Wikidata state.

Deprecation

At least 6 months' notice and 12 months' total support, signalled with Deprecation (RFC 9745), Sunset (RFC 8594), a Link rel="deprecation" and a block in the body. You should learn a sunset is coming from headers alone.

Reproducibility

Any response can be reproduced from its datasetVersions plus the build at the matching tag. A snapshot test fails the build if a route or response shape changes without the version moving — because that is exactly the change a caller would otherwise discover for you.