Compliance

Ruleset versioning

How Beliq versions its validation rules, how to choose which ruleset runs via channels and the Beliq-Ruleset header, and how ruleset changes are classified and announced.

Beliq judges every invoice against pinned authority artifacts — Schematron and XSD bundles published by the standards bodies. Those artifacts have versions, and they change over time. Two independent version axes decide which rules apply to your document:

The spec axis — the standard the document itself declares (for example XRechnung 3.0, via its CustomizationID). Beliq detects this from the document; it is not something you set.
The ruleset axis — the specific version of the rule artifacts Beliq bundles to check that spec. This page is about the ruleset axis: how it is versioned, how you choose which version runs, and how changes are announced.

For the exact artifacts and versions in force right now, see Validation artifacts.

Ruleset channels

A channel is a symbolic name for “which ruleset version to run, per format”, so you never hard-code version numbers. There are two:

Channel	What it selects
`latest`	The current ruleset for each format. This is the default — used when a request sends no `Beliq-Ruleset` header.
`previous`	The ruleset retained before the most recent breaking change, per format. Retention is gated on breaking changes (see How rulesets change), and there have been none, so today `previous` resolves to `latest` and the response flags `rulesetFellBack`. It becomes distinct from `latest` only after a breaking bump.

The selectable channels are also listed by the keyless GET /v1/rulesets endpoint, in its channels array.

Choosing which ruleset runs

Ruleset selection resolves with a fixed precedence, highest first:

The Beliq-Ruleset request header (per call).
Your organisation’s default channel.
The system default, latest.

Organisation default

In the dashboard, Settings → Default ruleset channel sets the channel every API key in your organisation validates against when a request sends no Beliq-Ruleset header. Only owners and admins can change it. This is the org-wide baseline — leave it on latest unless you have a specific reason to pin.

Per request

Send a Beliq-Ruleset header with the channel name to override the org default for a single call:

curl -X POST "https://api.beliq.eu/v1/validate?format=auto" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Beliq-Ruleset: previous" \
  --data-binary @invoice.xml

The header is effective on POST /v1/validate only. /v1/generate, /v1/convert, and /v1/parse accept it but ignore it — they always run the current bundled artifacts and do not perform Schematron verdict selection. To see which artifact versions those routes used, read the X-Version-Block response header (compact JSON with the same version fields as the validate body).

Seeing which ruleset ran

Every response tells you exactly what was applied:

Field / header	What it reports
`Beliq-Ruleset-Resolved` (response header)	The ruleset that was actually applied to the request.
`rulesetChannel` (body)	The channel applied — `latest` or `previous` — present when a non-default channel was selected (via the header or a non-`latest` org default).
`rulesetFellBack` (body)	`true` when `previous` was requested but the format retains no prior ruleset, so the request fell back to `latest`. Present only alongside `rulesetChannel`.

For the concrete artifact versions and checksums that judged your document, the response also carries the per-format version fields and the rulesetSha256 fingerprint. See Validation artifacts → API response metadata and Verify a hash.

How rulesets change

Beliq does not auto-update validation artifacts — every version bump is reviewed and tested before rollout. Changes fall into two classes:

Safe — a false-positive fix, a rule relaxation, a code-list addition, a refactor. A document that passed before still passes. Safe changes roll straight into latest, with no retained previous.
Breaking — a change that can make a previously-valid document newly invalid. Breaking changes are announced at least 90 days ahead, and the outgoing ruleset is retained as previous for a transition window so you can pin to it while you adapt.

The public record of what changed and when is the Validation artifacts → Version changelog. Beliq also runs a nightly content-SHA drift check against every pinned artifact and opens a tracking issue if an authority re-publishes an artifact without bumping its version.

Validation artifacts — the exact artifacts, versions, sources, and checksums in force now.
Verify a hash — reproduce rulesetSha256 and cross-check the ruleset against the public catalog.