railiance-master/schemas/README.md

Railiance family declaration schemas

Normative schemas for the repo-family declaration files. docs/repo-family-bootstrap-contract.md names the minimum fields; these schemas define their shapes and are the authority where the two disagree.

Family	Declaration path	Schema
rapp-*	declarations/rapp.yaml	rapp.schema.json
rail-*	declarations/rail.yaml	rail.schema.json
reef-*	declarations/reef.yaml	reef.schema.json

Written under RMASTER-WP-0021 from the drift survey routed by railiance-platform under its RAILIANCE-WP-0015 (State Hub messages 04c776c4, f88f938d).

The two cardinalities

These are the load-bearing rules. Everything the validator can usefully check follows from keeping them distinct.

• Repos to rapps is many-to-many. A repo may contribute to more than one rapp — a shared library, or a service that is a member of one bundle and a dependency of another.
• Deployables to rapps is one-to-one. Every running deployable has exactly one rapp that owns its rollout.

The second is what makes the coverage question well-formed: does every live deployable belong to exactly one rapp? That single check catches stale reef bindings, unpackaged live workloads, and the workload-count gap at once. It is what turns this schema from a one-shot lint into a standing control loop.

Rapp bounded context is therefore its own dimension, derived neither from Forgejo organizations nor from State Hub domains. A repo lives in exactly one Forgejo org, so org:repo is one-to-many, and a many-to-many grouping cannot be derived from a one-to-many one. Domains fail in both directions. See docs/adr/ADR-0007-rapp-declaration-contract.md and decision d07ee5f9.

Normative choices, and what they cost

The three live rapp declarations expressed their rollout, smoke and rollback contracts three mutually unreadable ways. The schema picks one shape. Where it picks, it says so and it says who pays.

default_mode is kept — all three declarations already carried it. No cost.

supported_commands becomes commands in all three contracts. Mechanical rename for rapp-openbao and rapp-postgres.

smoke_contract.required is required, and commands is optional. Taken from rapp-qonto. This is the one migration with real cost: the platform rapps declare only commands, so their owners must name the outcomes those commands establish. That cost is the point. A command list records what was run; a required list records what must be true. Only the second can be checked by anything other than the person who ran it.

rollback_contract.order is required. Taken from rapp-qonto. Recoverable from the command sequences the platform rapps already document, so the cost is low. direct_kubernetes_fallback generalizes to fallback.

workload_identity.name is the workload, never the repo, and the schema forbids the rapp- prefix on it outright. rapp-qonto currently sets it to rapp-qonto; the correct value is qonto.

contract_version, readiness_state, data_classification and criticality are required. All four exist only in rapp-qonto today. The first two are promoted because the rail family has carried them consistently in both rails and has not drifted — that contrast is the whole argument for schema. The second two are promoted because a package whose classification and criticality are unstated cannot be admitted to a reef on evidence.

consumer_contract is schema-defined but optional. Only rapp-postgres provisions isolated units to other services. Requiring it everywhere would be false precision.

Open question: what may ownership_repo name?

Currently rapp-openbao and rapp-postgres name railiance-platform, a layer repo, and rapp-qonto names qonto-assistant, an application repo.

The schema admits both, requiring only that there be exactly one and that it not be the rapp repo itself. This is deliberately the permissive reading, taken so the schema does not silently invalidate two of three live declarations on a question the survey cannot settle.

The tighter alternative is that ownership_repo must name the repo whose team is accountable for the workload in production, which would likely disqualify a layer repo that owns dozens of unrelated workloads. That is a modelling call about where accountability sits, not a lint, and it belongs to the architecture owner. Until it is made, treat the permissive rule as provisional.

Validator-only constraints

JSON Schema cannot express these; tools/validate-family-declarations.py does:

• primary_rail must appear in supported_rails (rapp) or hosted_rails (reef)
• reef bound_rapps, if present, must match the projection of rapp.bound_reefs
• a rapp ownership_repo must not be the rapp repo itself
• declared member repos, named rails, and named reefs must resolve on disk
• a deployable name may belong to at most one rapp

Rail schema (T04)

rail.schema.json codifies the two live rails. It does not tighten the family beyond current practice.

Required on every rail: kind, rail_id, repo, ownership_repo, contract_version, composition_kind, execution_architecture, readiness_state, required_substrate_capabilities, supported_rollout_modes.

composition_kind: derived additionally requires base_rail, base_rail_contract, inherited_semantics, overridden_semantics, and compatibility_constraints. A base rail must not carry those fields.

required_substrate_capabilities is the live name. The bootstrap contract's older substrate_prerequisites label is retired; do not reintroduce it.

Rail readiness_state uses the composition-contract vocabulary (declared, installed, verified, production-approved, deprecated). That is deliberately not the rapp vocabulary and not the reef lifecycle_state.

Validated 2026-08-13 against both live rails with jsonschema 4.10.3: both conform. That is the intended contrast with the rapp family.

Reef schema (T04)

reef.schema.json codifies the live reef-railiance declaration, with one normative change: bound_rapps is no longer a hand-maintained required field.

Required on every reef: kind, reef_id, repo, ownership_repo, substrate_kind, lifecycle_state, criticality, primary_rail, hosted_rails, current_members.

bound_rapps is optional. Its source of truth is rapp.bound_reefs. The validator inverts that field. If a reef still lists bound_rapps, the list must match the projection exactly.

Migration for reef-railiance. The current list is [rapp-qonto]. That is already stale: rapp-openbao and rapp-postgres are live on Railiance01. Until those three declarations name reef-railiance in bound_reefs, the derived projection is empty and a hand-list of anything fails. The owning repo should delete bound_rapps now, or replace it with the derived set once the rapps name the reef. Either is a one-line change; leaving the stale list is the failure mode this check exists to catch.

rapp.bound_reefs was added as a required field in the same task. An empty list is legal and means the package is declared but not yet placed.

Validated 2026-08-13 against the live reef: it conforms as a document. The bound_rapps value does not survive the derivation check, which is the intended result.

Runtime dependencies name capabilities, not resources

runtime_dependencies is a list of capability names (s3-backup-target, openbao-database-secrets-engine). The schema does not, and must not, say who provisions the thing that satisfies a name.

The postgres backup object store is the worked example. rapp-postgres declares s3-backup-target as a consumed capability. The bucket is a resource-control resource (RESOURCE-WP-0002). The credential is railiance-platform OpenBao custody (Secret platform-pg-backup-s3). Purchase itself is the escalated human decision 9c21c0e0. Until resource-control hands an endpoint to railiance-platform, make postgres-backup-deploy stays fail-closed on purpose. That is not a hole in rapp-postgres ownership and not a hole in this schema.

Running the validator

tools/validate-family-declarations.py
tools/validate-family-declarations.py --root ..
tools/validate-family-declarations.py --inventory path/to/live-deployables.json
tools/validate-family-declarations.py --self-test

--inventory is the T06 coverage check. This repo does not query a cluster. The file is produced by an implementation repo and must be a JSON mapping with a deployables list of {name, namespace?, kind?} (or bare name strings). Live names that no rapp claims are reported as wave-2 worklist items, not suppressed.

The validator is tools/validate-family-declarations.py (RMASTER-WP-0021-T05). It is runnable standalone now. Calling it from fix-consistency waits on the-custodian admitting the family prefixes; that sequencing is not ours.