Schema versioning

The API has two independent version axes:

• API version: the URL path (/v1/). It identifies the contract surface: endpoints, error model, authentication, streaming protocol.
• Dataset schema version: the shape of records within each dataset. Each dataset carries its own schema version and changes on its own timeline.

Both follow Semantic Versioning 2.0: patch releases change documentation or fix bugs without changing behavior, minor releases are additive, and major releases can break existing clients.

API versioning

The API is path-versioned. Within a major API version, changes are only minor or patch, so a client that integrated against /v1/ keeps working against /v1/. If a /v2/ ever ships, both versions run in parallel for at least 12 months from the date /v2/ is generally available.

Changes to the /v1/ surface are recorded in the changelog.

Dataset schema versioning

Every dataset response advertises the schema version of its payload:

X-Schema-Version: sanctions=1.2.0

Each dataset is versioned on its own: adding a field to the sanctions schema bumps sanctions, and the pep schema is unchanged. Each dataset publishes its own release history, the sanctions changelog and the PEP changelog.

Pinning a version

By default, responses use the dataset’s current version, reported as current by the version manifest. Pin a version in one of two ways:

1. Query parameter:

   ?schema_version=1.2

2. Media type parameter on Accept:

   Accept: application/x-ndjson; schema-version=1.2

When both are present, the query parameter wins.

A pin is major, major.minor, or an exact major.minor.patch, and resolves to the newest served version matching it: ?schema_version=1 rolls forward to the newest 1.x, while ?schema_version=1.2.0 selects that release exactly.

A pin that names no served version is answered 406 Not Acceptable with error.code = "schema_unsupported". A version that was served and has since been withdrawn is answered 410 Gone with error.code = "schema_withdrawn". Neither body lists the supported versions: read them from the version manifest.

Compatibility guarantees

• Within a major version, schema changes are additive: new fields appear, but no existing field is removed, renamed, or retyped.
• Across majors, at least one prior major stays supported in parallel for at least 12 months from the next-major release, and both can be pinned during that window.
• Entity datasets publish closed schemas: their JSON Schemas set additionalProperties: false and constrain fields such as topics[] with enums. A new enum value breaks strict consumers such as generated clients and response validators, so adding one is a major bump, not a minor one.

Discovering versions

Schema documents are published by the API itself, without authentication:

• GET /v1/schemas/{domain}: version manifest for a dataset.
• GET /v1/schemas/{domain}/{major}: JSON Schema for the latest version within a major.
• GET /v1/schemas/{domain}/{version}: JSON Schema for an exact version. 406 for never-released versions, 410 for withdrawn ones.