Understand generated files

View as Markdown

Registry Relay derives two kinds of output from one authored project: review material for the people who approve the contract, and a sealed package for the operator who runs it. Both are derived from authored intent. Neither is a second place to configure the service.

Keep one source of truth

Edit registry.yaml and the governance records, codelists, semantic profiles, and fixtures it references, then rerun the command that owns the output. A generated file that disagrees with the contract is a stale run, not a correction. Editing one changes nothing that Relay serves: the runtime rebuilds the same material from the contract at startup and refuses a package whose derived bytes differ.

Review output

relayctl generate writes into generated/ inside the project unless --output names another directory. It refuses a destination that already holds content, so a generated tree is always the product of exactly one run.

Path	What it carries
`openapi.full.yaml`	Every compiled operation, including operator-only ones
`openapi.public.json`	The description Relay serves to unauthenticated callers
`artifacts/`	Capability inventories, JSON Schema, SHACL shapes, JSON-LD vocabularies and contexts, classification and processing descriptions, the audit event schema, and SDMX structures
`reports/identification-report.json`	Which source columns the identification pack flagged, and why
`reports/classification-inventory.json`	The effective classification of every published property
`reports/access-profile-report.json`	What each access profile lets a caller reach
`reports/contextual-review-findings.json`	Combinations a reviewer should look at before approving
`governance/classification-review-starter.yaml`	A starting point for the review record the production profile requires

Every one of these is derived from the contract and the observed source structure. None of them carries a source row value.

The sealed package

relayctl package writes one new directory and refuses a destination that already exists. It recompiles the project under the production profile first, so a revision that would fail relayctl check --production cannot be sealed.

Path	What it carries
`relay-package.json`	The manifest: package version, `packageRevision`, contract revision, source schema fingerprints and observed schemas, the artifact list with its operation bindings, and one entry per file
`registry.yaml`	The contract exactly as authored
`governed/`	Every governance file the contract references, plus the classification review rationale and its accepted identification report
`compiled/registry.json`	The canonical compiled Registry
`generated/`	The artifact set, keyed to the manifest entries

The package’s generated/ directory holds the artifact set only. The review reports and the review starter stay in the authoring project: they are inputs to approval, not deployment material.

A package carries no database, no runtime.yaml, no secret, and no fixture. The operator supplies those at the deployment. Packaging refuses oversized input instead of truncating it: at most 256 referenced governance files totalling 16 MiB, 1024 package files totalling 64 MiB, and a 4 MiB manifest.

What packageRevision proves

packageRevision is a SHA-256 digest over the canonicalized manifest. It detects a modified, truncated, or reassembled package. It is not a signature, and anyone who alters a package can recompute it, so authenticity stays a property of how the institution transfers, stores, and restricts the directory.

Acceptance does not stop at the digest. Loading a package re-reads every listed file, compares each size and SHA-256, recompiles the Registry from the governed files under the production profile, regenerates the whole artifact set, and requires byte-for-byte equality before the service opens a listener.

Visibility travels with each file

Every manifest entry records whether the file is public, operation-bound, or operator-only, and whether it was generated or authored. The split is plain in the two OpenAPI documents: openapi.public.json is what Relay returns from /openapi.json, while openapi.full.yaml describes every compiled operation, including the ones no anonymous caller can reach.