Versioning

Three things version independently here, and conflating them is how APIs break their callers.

The three axes

Axis	Looks like	Moves when
API contract	`/chem/v1/`	Only on a breaking change. A new version does not retire the old one for at least 12 months.
Dataset version	`ecfr-cfr-2026.1`	The upstream data or the build that shapes it changes. Carried on every response as `datasetVersions`.
CFR issue	`2026CFRRev19`	eCFR publishes a revision — several times a year. This is their number, carried verbatim, not mine.

A new CFR issue changes composition limits. That is data moving, not a contract breaking, so it is additive: your client keeps working and the numbers change, which is the entire point of the service. Every response carries cfrIssueDate so you can tell which schedule answered you.

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 the type or units of a response field.
Removing an endpoint, or changing its path.
Adding a required request parameter.
Tightening validation so a previously accepted request now fails.
Changing a default value, page size or sort order.
Changing the meaning of an existing field without renaming it.
Changing the shape of a record inside a published dataset.

Additive

Adding an endpoint, a response field, or an optional request parameter.
Widening validation so a previously rejected request now succeeds.
Correcting data values, or rebuilding from a newer CFR issue.

Deprecation

At least 6 months' notice and 12 months' total support. While a version is deprecated every response carries a Deprecation header (RFC 9745), a Sunset header (RFC 8594), a Link rel="deprecation" to the migration notes, and a deprecation block in the body. You should learn a sunset is coming from headers alone, without polling a changelog.

Reproducibility

Any response can be reproduced from its datasetVersions and cfrIssueDate plus the build in the repository at the matching tag. The machine-readable form of all of this is at /v1/version, and a snapshot test in the repository fails the build if a route or a response shape changes without the version moving — because that is exactly the change that otherwise gets noticed by a caller instead.