Versioning Policy

Last updated: April 5, 2026

EuroValidate follows Semantic Versioning 2.0.0. This document describes what changes we consider breaking, how long older versions remain supported, and how to stay ahead of upcoming changes.

URL versioning

The API is versioned in the URL path: /v1/*. A new major version (/v2/*) is only introduced when we cannot avoid backwards-incompatible changes. Both versions run in parallel during the deprecation window.

What counts as a breaking change

We treat the following as breaking and will only ship them in a new major version:

Removing or renaming an endpoint, field, or query parameter.
Changing the type, format, or semantics of an existing field (e.g. int → string, "valid":true → "status":"ok").
Changing HTTP status codes returned for well-defined outcomes (e.g. replacing 200 with 201 on an existing create endpoint).
Making an optional field required, or tightening validation in a way that previously-accepted input starts to fail.
Changes to the authentication scheme, error envelope (currently RFC 9457), or pagination contract.

What we can change without a new major version

Adding new endpoints, fields, query parameters, or enum values as long as clients can safely ignore them.
Returning additional metadata in the meta block.
Improving error messages (the type URI and status are stable; the detail string can improve).
Changing internal caching behaviour, latency, confidence-scoring thresholds.
Adding new upstream sources or failover logic.

Clients should be written to tolerate unknown fields in responses.

Deprecation process

When we plan to deprecate an endpoint or field we announce it at least 6 months before removal.
Deprecated endpoints return a Deprecation and Sunset HTTP header (per RFC 8594) and a X-EuroValidate-Deprecation header with a link to the migration guide.
Deprecation announcements go out via: the changelog, email to active customers, a blog post, and the /v1/status response.

Support window for major versions

Event	Minimum notice
Next major version announced	6 months before release
Old major version receives security fixes only	12 months after successor release
Old major version shut down	24 months after successor release

Pre-1.0 (beta)

Until we reach 1.0.0 (current version: 1.0.0-beta.1), we reserve the right to make breaking changes in minor releases. We will still give at least 4 weeks' notice via email and the changelog, and will never change contracts silently.

Client version header

We recommend sending an X-EuroValidate-Client header with each request so we can notify you proactively when you are on a soon-to-be-deprecated version:

X-EuroValidate-Client: eurovalidate-python/2.3.0
X-EuroValidate-Client: my-checkout-service/1.4.7

Beta & preview features

Features marked as beta in the documentation are not subject to this policy. They may change or be removed with 30 days' notice. Beta features are always explicitly labelled (in the endpoint description and in the meta.stability field of the response).

Questions

Planning a large integration and need additional commitments? Email [email protected].