eliDocs
/
Compliance

How verification works

A plain-language explanation of the hashes on a /v1/validate result, what a hash is, why Beliq puts them on every result, and how you can use them to check the result yourself.

When you validate an invoice with Beliq, you get back a verdict: valid or not, with the specific rules that failed. Every result also carries a few extra values that let you confirm the verdict yourself, without taking Beliq’s word for it. Those values are hashes. This page explains what they are and why they are worth caring about. For the exact commands, see Verify a hash.

What a hash is

A hash is a short fingerprint of some data. You feed in a file (or any string of bytes), and a hash function gives back a fixed-length value, for example a 64-character string of hex digits. Beliq uses SHA-256, a standard hash function built into every operating system and programming language.

Three properties make it useful here:

  • Same input, same fingerprint. Hash the same bytes on any machine, in any language, and you get the identical value. Beliq and you can compute it separately and compare.
  • Any change shows. Flip a single byte, add a space, re-save in a different encoding, and the fingerprint changes completely. There is no “close enough”: it either matches or it does not.
  • It only goes one way. The fingerprint reveals nothing about the original data, and you cannot work backwards from it. So a hash is safe to store, log, or hand to an auditor.

In short: a hash lets two parties confirm they are looking at the exact same bytes, without either of them having to send or reveal the bytes themselves.

Why Beliq puts hashes on a result

A validation result is a claim: “this document is valid (or not) against these rules.” For that claim to be trustworthy, two things have to be true, and normally you would simply have to trust them:

  1. Beliq judged the exact file you sent, not a truncated, re-encoded, or substituted version.
  2. Beliq judged it against the rules it says it uses, not some other or outdated set.

The hashes turn both of those from “trust us” into “check it yourself.” You do not need access to Beliq’s servers, and you do not need to run anything proprietary. The standard sha256 tooling already on your machine is enough.

The values on a result

A POST /v1/validate response carries these verifiability fields:

Field What it is a fingerprint of What checking it proves
sha256 The exact request body Beliq validated. The result applies to your precise file, byte for byte.
rulesetSha256 The full set of rule artifacts that judged the document, as one combined fingerprint. Which ruleset judged you, captured in a single value you can reproduce.
rulesetArtifacts Each individual rule artifact that ran: its name, version, and own fingerprint. The building blocks behind rulesetSha256, so you can rebuild it and cross-check each part.

sha256 is always present. rulesetSha256 and rulesetArtifacts are present whenever a ruleset actually ran.

A result may also carry driftCheckedAt. This one is not a hash but a timestamp: it reports when the rule artifacts that judged your document were last confirmed to still match their source at the authority that publishes them. Beliq re-checks this on a schedule, and the value is a conservative lower bound, meaning “confirmed at least as recently as this,” never a claim of being fresher than a check that actually ran. It is present when that confirmation is current for every artifact used, and left off otherwise. See Verify a hash for the detail.

How you use them

Three independent checks, each one step, each using only values you already have:

  1. Confirm your file. Hash your local invoice with sha256sum and compare it to sha256 in the response. A match means Beliq judged your exact bytes.
  2. Reproduce the ruleset fingerprint. Combine the rulesetArtifacts rows in a fixed way and hash them: the result equals rulesetSha256. A match means the fingerprint is internally consistent.
  3. Cross-check against the public catalog. Look up each artifact in the keyless GET /v1/rulesets endpoint and confirm it appears there with the same version and fingerprint. A match means the rules that judged you are the ones Beliq publishes for everyone.

The exact commands (jq, Python, and shell) are on the Verify a hash page.

Why this is useful to you

  • An audit trail you control. Store the response, including its hashes, alongside the invoice in your own records. Months or years later you can prove which file was judged and which ruleset judged it, without asking Beliq to confirm anything.
  • Evidence in a dispute. If a counterparty or auditor questions a result, you can demonstrate, with standard tooling, that the validated document was exactly the one in your records and that the rules applied were the published ones.
  • Tamper and corruption detection. If a transmission silently corrupts a file, or a document is altered after validation, the sha256 no longer matches, and you notice.
  • Trust that does not depend on Beliq staying online. The checks run entirely on your side from values you already hold. The verification does not rely on a live call back to Beliq (the catalog cross-check is the one optional online step, and it is keyless and free).

What the hashes do and do not prove

The fingerprints make the result transparent and self-consistent, and tie the ruleset to a value Beliq publishes openly. There is a limit worth understanding:

  • For XSD-only national formats (Italy, Spain, Slovenia), the pinned rule artifact is the authority’s own file, vendored byte for byte. You can reproduce its fingerprint directly from the authority’s published download.
  • For the EN 16931 Schematron families (EN 16931 base, XRechnung, Peppol BIS, Factur-X, NLCIUS), the pinned artifact is a compiled version that Beliq builds from the authority’s published rule sources. So its fingerprint proves that the artifact Beliq ran is the one Beliq pins and re-verifies, not a value you can reproduce by hashing the authority’s raw source file directly.

The Verify a hash page covers this boundary in full, including the scope of the public catalog for provisional national formats.

Verification tiers

The hashes prove which ruleset judged your document. A separate question is how rigorously that ruleset itself has been verified against the authority’s intent, and this varies by format because authorities publish different verification materials. Beliq states this openly per format rather than implying every valid verdict rests on the same footing.

There are three tiers. Each format’s tier is a field on the keyless GET /v1/rulesets response (verificationTier), so you can read it programmatically.

Tier What it means How Beliq verifies it
conformance-verified The rules that judge your document have verdict parity with the authority’s own test suite. Beliq runs the authority’s per-rule unit-test corpus and asserts, rule by rule, that it fires (or stays silent) exactly as the authority’s suite declares.
builder-round-trip A real business-rule ruleset runs, but the authority publishes no per-rule test suite to check it against. Correctness is evidenced by the authority’s positive sample invoices plus round-trips through Beliq’s own generator, not by a per-rule verdict oracle.
xsd-structural Structural validation only: the document matches the authority’s XML schema, with no business-rule layer. The authority publishes an XSD but no machine-readable business rules (Schematron or equivalent), so valid means schema-valid, not business-rule compliant.

Per format:

Format Tier
EN 16931 (base), XRechnung, Peppol BIS 3.0, NLCIUS conformance-verified
Factur-X, ZUGFeRD builder-round-trip
Italy FatturaPA, Spain Facturae, Slovenia e-SLOG xsd-structural

On Beliq’s public coverage and marketing surfaces these three tiers roll up into two badges: conformance-verified and builder-round-trip both show as Authority-checked (the format authority’s own rulebook runs, pinned by version and hash), while xsd-structural shows as Schema-checked. A third badge, Community-checked, is reserved for formats checked against an independent published rulebook where the authority publishes none; no format carries it today.

The tier is a different axis from a format’s compliance status: it describes the verification method, not the promotion level. A valid result on an xsd-structural format confirms the document is schema-valid; it does not claim EN 16931 business-rule compliance, and the response omits schematronVersion to signal that.