Skip to content
VERASPEC
Repository
The conformance validatorstable

Command line

bash
ver-validate FILE... [--schema 1.0.0|1.0.1|1.1-draft] [--level auto|L0|L1|L2|L3]
[--spaces REGISTRY.json] [--format text|json]
[--max-bytes N] [--signature-key KEY.pem]
[--ignore CODE[,CODE...]]
[--registry SNAPSHOT.json] [--lineage-peer RECORD.json]...
[--profile default|high-trust]

--registry, --lineage-peer and --profile reach rules that exist only under --schema 1.1-draft; they are accepted and inert otherwise. --spaces and --registry take different documents and each has its own loader: --spaces takes a registry of embedding space descriptors (VER402), --registry takes a VER Registry snapshot of governed value-space tokens (VER1205).

console
$ ver-validate spec/example-record.json --schema 1.0.0
spec/example-record.json: FAIL (2 error(s), 1 warning(s)) [schema 1.0.0, level L3, claimed L3, status nonconformant]
warning VER308 /provenance/signature
Level L3 records SHOULD carry provenance.signature; none is present.
fix: Sign the record (RFC 8785 JCS canonicalization, detached JWS or COSE_Sign1) ...
error VER801 /identity/perceptual/0/value
pdq/1.0 digest is 96 characters; the algorithm is 256-bit and requires exactly 64 ...
error VER1302 /metadata/raw/0/sha256
raw segment icc declares sha256 5e884898..., but the carried bytes hash to bd3f0d3a...

Exit codes. 0 every record is conformant · 1 at least one record has an error-severity issue · 2 the invocation was wrong (bad option, unreadable file, unloadable key, missing standards tree). Warnings never change the exit code: a record that only warns is conformant. An indeterminate run (VER001: a rule crashed) exits 1, because the run did not establish conformance — read status, not the exit code, to tell "this record is wrong" from "this validator could not say".

A bad invocation is never charged to a record. A --signature-key that cannot be parsed exits 2 with a message about the key — it is not reported as a failed signature, because "I could not attempt the check" and "this record was modified after signing" are findings about different parties. Same for an unrecognized --ignore code and an unknown level=.

A batch is not all-or-nothing. One unreadable file does not discard the reports already computed: every readable file is validated and printed, each unreadable one is listed (NOT VALIDATED, and on stderr), and the run exits 2 because the invocation named something that is not there. A CI sweep over a directory that loses all its output to one stale path is useless.

--ignore moves the exit code, never the verdict. Suppression is a deployment policy — "this fleet tolerates VER404 until Q4" — and a deployment does not get to decide what the standard says. So the report keeps its unfiltered issues, ok and status, records the policy beside them as ignored_codes and ok_after_policy_exceptions, and prints both answers; only the exit code follows the filtered one, because moving the exit code is the whole reason the flag exists. An unregistered code is a usage error, not a silent no-op.

console
$ ver-validate --ignore VER602 record.json
record.json: FAIL (1 error(s), 0 warning(s)) [schema 1.0.1, level L0, claimed L0, status nonconformant]
error VER602 /embeddings/0/dtype
embedding dtype 'fp16' does not equal the descriptor dtype 'fp32'.
fix: A different dtype is a different space. Mint a new space_id or correct the embedding.
standards result: FAIL (1 error(s), 0 warning(s), status nonconformant) — unfiltered, above
policy result: ok (0 error(s), 0 warning(s)) after ignoring VER602 — the exit code follows this line
suppressed by --ignore: VER602 — exit code only. …
$ echo $?
0

An earlier version deleted the suppressed findings and recomputed ok. That made the report indistinguishable from one for a record with no such defect: the echo lived only in the CLI's own text, so a JSON report saved to an artifact store or piped onward travelled claiming the standard had cleared a record it had not. --ignore VER001 is the sharpest case — it buys an exit code and nothing else, because status keeps saying indeterminate.

--format json contract

jsonc
{
"profile": "vera-profile/1.0", // "vera-profile/1.1-draft" under --schema 1.1-draft
"ok": false, // the STANDARDS answer over every record; unfiltered
"status": "nonconformant", // conformant | nonconformant | indeterminate
"ok_after_policy_exceptions": true, // the policy answer; null when --ignore was not used
"ignored_codes": ["VER602"], // [] when --ignore was not used
"results": [
{ "path": "record.json", "report": { /* serialized VeraValidationReport */ } }
],
"unreadable": [ // present only when a named file could not be read
{ "path": "gone.json", "error": "…" }
]
}

Every key except unreadable is always present. The top-level ok, status, ok_after_policy_exceptions and ignored_codes aggregate the per-record reports, which carry the same four fields individually. A file in unreadable makes the aggregate status indeterminate and the run exit 2: nothing was established about it, so a batch verdict of "conformant" would be reporting on a smaller set of records than the invocation named. The exit code follows ok_after_policy_exceptions when it is not null, and ok otherwise.