eliDocs
/
API Reference

GET /v1/rulesets

GET/v1/rulesets

Public, keyless reference for the ruleset versions and artifact hashes Beliq pins per supported format. No API key, no quota cost.

GET /v1/rulesets is the machine-readable mirror of what the docs and landing page publish: the active ruleset version for each supported format, the ruleset channels you can pin, and the ruleset-hash catalog you cross-check a validation result against. It is the discovery counterpart to validation artifacts and verify a hash.

Access

This endpoint is public. It takes no API key, does not count against your monthly quota, and touches no database or engine. It stays IP-rate-limited like other keyless traffic. The response is a constant projection of the coverage data Beliq ships, so it is safe to poll and cache.

rulesets.sh
curl https://api.beliq.eu/v1/rulesets

The endpoint accepts no query parameters.

Response

A 200 returns the standard success envelope with three arrays under data:

{
  "success": true,
  "data": {
    "rulesets": [ /* one entry per publicly-supported format */ ],
    "channels": [ /* selectable ruleset channels */ ],
    "artifacts": [ /* the ruleset-hash catalog */ ]
  }
}

rulesets[]

One entry per format Beliq supports on the API surface. Each entry separates the two version axes: specVersion is the format spec a document declares; rulesetVersion is the bundled artefact Beliq actually runs, and the only axis that can move under you.

Field Type Meaning
format string Format identifier, for example xrechnung, factur-x, peppol-bis.
label string Human-readable format name.
standard string The standard the format derives from, for example EN 16931 CIUS - UBL & CII.
authority string The body that publishes the ruleset, for example KoSIT.
region string The country or region the format serves.
specVersion string Spec/display axis: the format spec version a document declares.
rulesetVersion string Ruleset/artefact axis: the bundled artefact release Beliq runs. The audit anchor.
rulesetArtefact string Provenance label for the artefact, for example XRechnung Schematron.
versionKey string Stable handle for the ruleset axis. Joins an entry to its rows in artifacts[].
verificationTier string | null How rigorously the format’s validation is backed. One of conformance-verified, builder-round-trip, xsd-structural, or null (only for a format that runs no validation artifact).
releaseDate string | null Release date of the pinned artefact, YYYY-MM-DD, or null.
repo string | null Source repository of the authority artefact, or null.
tag string | null Release tag in that repository, or null.

verificationTier reflects how the format is backed, not its compliance status:

  • conformance-verified: verdict parity against the authority’s own per-rule test corpus.
  • builder-round-trip: a real business-rule Schematron runs, evidenced by builder round-trips and the authority’s positive samples (no per-rule corpus published upstream).
  • xsd-structural: structural XSD validation only; no machine-readable business rules exist for the format.

channels[]

The ruleset channels selectable via the Beliq-Ruleset header on POST /v1/validate. Static: the two channels exist regardless of format.

Field Type Meaning
id string latest or previous.
label string Display label.
description string When the channel applies, including the fallback behaviour of previous.

artifacts[]

The ruleset-hash catalog: every rule artifact that can run for a publicly-supported format, with the SHA-256 of its exact file bytes. This is the allowlisted public subset of the engine’s registry; provisional national formats run pinned artifacts that are intentionally omitted here.

Field Type Meaning
key string Artifact key, for example en16931_cii_schematron. Matches a ruleset entry’s versionKey.
version string The registry label for the exact file. It may carry a format prefix, for example XRechnung-2.5.0 for the pack a ruleset entry names as 2.5.0 in rulesetVersion.
fileSha256 string Lowercase-hex SHA-256 of the artifact file, 64 characters.

A Schematron family compiles to more than one XSLT (a CII arm and a UBL arm), so one key and version can appear on several rows with different fileSha256 values.

Example

{
  "success": true,
  "data": {
    "rulesets": [
      {
        "format": "xrechnung",
        "label": "XRechnung",
        "standard": "EN 16931 CIUS - UBL & CII",
        "authority": "KoSIT",
        "region": "Germany",
        "specVersion": "3.0.2",
        "rulesetVersion": "2.5.0",
        "rulesetArtefact": "XRechnung Schematron",
        "versionKey": "xrechnung_schematron",
        "verificationTier": "conformance-verified",
        "releaseDate": "2026-01-31",
        "repo": "itplr-kosit/xrechnung-schematron",
        "tag": "v2.5.0"
      }
    ],
    "channels": [
      {
        "id": "latest",
        "label": "Latest",
        "description": "The current ruleset for each format, the default when no Beliq-Ruleset header is sent."
      },
      {
        "id": "previous",
        "label": "Previous",
        "description": "The ruleset retained before the most recent breaking change, per format. Retention is gated on breaking bumps; with none retained yet, previous resolves to latest and the response flags rulesetFellBack."
      }
    ],
    "artifacts": [
      {
        "key": "en16931_cii_schematron",
        "version": "1.3.16",
        "fileSha256": "0b234dea2bbfee739b7761e607a992c17fab88773014ef56355b6158cfb1cc53"
      },
      {
        "key": "xrechnung_schematron",
        "version": "XRechnung-2.5.0",
        "fileSha256": "0cadcbde2eb320c2e7e83a8057b93bc48076e223dda36308e31704684ee9ecf3"
      },
      {
        "key": "xrechnung_schematron",
        "version": "XRechnung-2.5.0",
        "fileSha256": "ce8f257114eccb49d369a2c77c6cccd7d3cd9f1286e9ff158b543a1311182b2a"
      }
    ]
  }
}

Verifying a validation result

Every POST /v1/validate response for a publicly-supported format carries a rulesetSha256 and its rulesetArtifacts components. To confirm the ruleset that judged you is the one Beliq pins for everyone:

  1. Check that each component in your response’s rulesetArtifacts appears in artifacts[] here (match on key, version, and fileSha256).
  2. Reproduce rulesetSha256 yourself: sort the "<key>@<version>=<fileSha256>" lines, join them with newlines, and take the SHA-256.

The reproduction needs only the values in your own response, so it works for any result. For the national XSD formats, which Beliq vendors byte for byte, you can also reproduce fileSha256 straight from the authority’s own download. See how verification works and verify a hash.