Validate your project

View as Markdown

Use these checks after you change a Registry Relay contract, a governance record, a codelist, a semantic mapping, or a fixture. Every check is read-only: none of them starts a service, resolves a secret, or writes to the institution’s database. relayctl reads no environment variables, so what you pass on the command line is the whole input.

Compile and validate

relayctl check ./business-registry

check parses the contract, validates it against the observed SQLite schema, expands classifications, and derives the access and disclosure plans. A successful report carries the contract revision and the compiled configuration key paths. A failed report carries diagnostics with a stable code and a location, and no source values.

Require reviewed governance

relayctl check ./business-registry --production

The production profile requires that every generated suggestion has been reviewed. It refuses unreviewed semantic or classification suggestions, a missing, stale, or digest-mismatched classification review, source-schema drift, and inconsistent access or disclosure rules. This is the same profile relayctl package compiles under, so a revision that fails here cannot be sealed.

Replay fixtures offline

relayctl test ./business-registry
relayctl test ./business-registry --fixture filtered-page

test runs the project’s expected requests and responses through the same compiled router the service uses, against the synthetic fixture database. The report lists each step with its expected status, observed status, and a passed flag. --fixture runs exactly one step, named by its identifier, and refuses an identifier the journey does not declare. A step that compares itself to an earlier step, such as one asserting the same records across formats or the same entity tag, passes only in a full run.

Generate the review inputs

relayctl generate ./business-registry

generate writes the artifact set and the deterministic value-free review reports. Without --output it writes to generated/ inside the project. It refuses a destination that already holds content, so remove or rename the previous directory before regenerating.

Classify what changed

relayctl diff ./approved-business-registry ./business-registry

diff compiles both projects and reports each change with a class, a location, a description, and an impact of informational, narrowing, widening, or breaking. Widening covers the changes that let a caller reach more than the previous revision allowed, such as an added access profile, an expanded disclosure profile, or relaxed handling. Attach the report to the change review; diff approves nothing by itself.

Read the exit status

Exit code	Meaning
`0`	The command succeeded
`1`	A domain refusal: a check, review, or fixture step failed
`2`	A usage error in the command line
`3`	An operational failure, such as an unreadable input or an unwritable output

Add the global --json flag to emit the report without the command header line for local automation.

What these checks do not prove

Local success does not prove source interoperability, operator acceptance, or production readiness. It says the reviewed contract compiles, that its governance inputs are complete, and that the supplied synthetic requests behave as the publisher expects. An institution still reviews meaning and disclosure, and an operator still binds and activates the sealed revision.

Evidence Gateway projects are validated separately with their own toolset; see test an Evidence Gateway project with fixtures.