Migration guidestable

§2 Tooling

Everything below assumes the conformance profile validator. Run it straight out of the tree — no install is needed. From the repository root:

bash

PYTHONPATH=packages/ver-validator/src .venv/bin/python -m ver_validator.cli \
    conformance/valid/l3-full.json

Every command in this guide is written in that form, and every one of them runs verbatim from the repository root against a path that exists in this tree. Substitute your own Record paths.

If your virtualenv has pip, an editable install gives you a shorter invocation:

bash

# alternative — requires a venv with pip and setuptools.
# This repository's .venv ships neither, so the no-install form above is the
# one that works here.
.venv/bin/python -m pip install -e packages/ver-validator
ver-validate conformance/valid/l3-full.json

Useful flags for migration work:

Flag	Use
`--schema 1.0.0` / `--schema 1.0.1`	Validate the same Record against both releases and diff the reports
`--level` (`auto`, `L0`, `L1`, `L2`, `L3`)	Override the Record's own conformance claim; `auto` uses the claim, defaulting to L0
`--format json`	Machine-readable report for a CI gate
`--spaces REGISTRY.json`	Check inline descriptors against your published registry (`VER402`, space immutability)
`--ignore CODE[,CODE…]`	Drop named codes from the report and recompute the exit status — for a rule you have deliberately accepted. Codes are stable, so a suppression means the same thing next year (ADR-0003)

Exit codes: 0 clean, 1 errors present, 2 usage error. Warnings never set a non-zero exit; decide for yourself which warnings your CI treats as blocking.

Programmatic use — run the interpreter with the same PYTHONPATH if you have not installed the package:

bash

PYTHONPATH=packages/ver-validator/src .venv/bin/python -c '
from ver_validator import validate_file
report = validate_file("conformance/valid/l3-full.json", schema="1.0.1")
for issue in report.issues:
    print(issue.code, issue.json_pointer, issue.message)
print("ok:", report.ok, "effective level:", report.level_effective)
'