Release definition schema design
Status: draft design, 2026-10-20. This is the pre-implementation schema document permitted by DPP-056. It defines implementation requirements. It is not a generated schema, a served API or an implementation-start receipt.
The authoring contract defines release-definition@v1. DPP-002 must establish the canonical owner model before DPP-056 generates its JSON Schema. The visual editor, CLI and text endpoints must serialize that model through one owner contract.
Start conditions
- Satisfy PG-1: close the predecessor tasks and follow-ups with criterion evidence, CCP-045’s final CA-01–CA-14 acceptance, and CCP-053’s installation/upgrade/restore proof.
- DPP-001 checks that evidence and records the accepted source, deployment and contract handoff.
- DPP-002 lands the release/deployment-configuration revision model, persistence and typed owner contract. DPP-056 serializes that model; an existing component manifest is not its substitute.
- Integrate DPP-004 descriptors, DPP-006 setting states, DPP-007 application inputs and DPP-008 secret references as their contracts become available. Share canonical identity with DPP-011 and capability validation with DPP-057. These integration requirements do not add a new whole-program acceptance gate to the existing DPP-056 start dependency.
The current operator prerequisites and issued grants belong to the predecessor’s acceptance manifest. Read its latest reconciliation before requesting authority; previously granted setup is not a new approval request. More worktree capacity cannot replace acceptance evidence or an owner model.
Document sections and schema responsibilities
The root object contains only the following declared sections. Reject unknown properties at each typed object boundary. Explicitly declared maps and descriptor parameters accept only keys allowed by their owning schema.
| Path | Required design | Owner/model binding |
|---|---|---|
$schema | Export names the generated versioned schema. Reading a document does not fetch this URL. | DPP-056 generated artifact and export envelope. |
metadata | Format/schema version, release name/version and declared description; tenant-free portable identity. | DPP-002. Authentication determines the tenant; the document cannot select one. |
contents.services[] | Stable node/component identity, display data, digest-pinned artifact and target binding. | DPP-002 and the existing component/artifact catalogue. |
contents.plugins[] | Stable node identity, digest-pinned artifact, consumer service reference and compatibility metadata. | DPP-002 attachment model; the consumer must exist. |
contents.dependencies[] | References between declared nodes with started, healthy, job-succeeded or plugin-activated readiness. | DPP-002 graph; shared validation with DPP-010. |
pipeline.operations[] | Ordered operations referencing extension: <id>@<version> and only its descriptor’s typed fields. | DPP-002 operation model and DPP-004 descriptors. Catalogue presence and target admission are separate checks. |
configuration.primitives | Per-field inherit or explicit(value); descriptor bounds and policy constraints remain enforced. | DPP-006 and the selected deployment-configuration revision. |
configuration.inputs | Typed application input declarations and their declared binding/precedence sources. | DPP-007; do not confuse application values with executor controls. |
configuration.secrets | Provider/path references and exact or resolve-at-dispatch version policy; no secret value property. | DPP-008 and the existing provider/broker boundary. |
layout | Declared canvas coordinates and collapsed state. Round-trip without changing semantic identity. | DPP-002 presentation projection. |
x-stellaops | Schema revision, exported-from source revision and authoring-contract URL. | Server-written export metadata; never authority supplied by an imported document. |
The final property names, required/optional rules, identifier types, map shapes and descriptor unions must come from those owner models. Do not fill unresolved definitions with arbitrary additionalProperties, free-form metadata or a second set of production DTOs.
Generate field-level schema annotations for the authoring contract’s four mutability classes: author-mutable, catalogue-mutable, policy-locked and presentation-only. Schema annotations are distinct from the document’s export-provenance block. DPP-059 checks each exact field’s classification against the generated schema; preserve server-written schema selection and provenance.
Policy constraints remain owner-enforced and visible as read-only information. An author cannot change trust, grants, admission, mandatory gates or approved path roots through a document. Catalogue-mutable values must resolve to an allowed catalogue entry. A syntactically valid digest or extension version is insufficient.
Normalization and identities
Canonical output is JSON. YAML input is parsed into the same owner model, then follows the same validation and normalization path. Duplicate properties, unsupported YAML constructs and ambiguous values must fail before a draft is created; select parser limits and supported constructs during implementation using the repository dependency gate.
Use the existing canonicalization and configured cryptography abstractions. Do not implement a second canonical JSON or hashing algorithm. Record three distinct subjects:
| Subject | Rule |
|---|---|
| Canonical authoring document | Deterministic serialization of the owner model, including declared presentation/export fields. Whitespace and input property ordering do not change normalized bytes. |
| Definition semantic identity | The owner’s semantic projection, excluding layout and export provenance. An export’s changing source revision cannot change semantic identity by itself. Include schema identity and every execution-relevant authored field. |
| Compiled plan identity | DPP-011 binds the definition identity to exact configuration/profile/schema revisions, effective settings, resolved digests, targets and extension versions. A definition hash alone is not an approved plan. |
DPP-002 must classify display-only fields consistently with the architecture; display-only labels must not enter execution identity accidentally. DPP-056 must not guess that classification independently.
Keep array order where it carries meaning, including ordered operations. Apply only ordering rules declared by the owner model for sets/maps. Preserve explicit false and 0; do not collapse explicit(value) into inherit. Follow the primitive state rules for null, empty values, reset and omission.
Round-trip assertions compare authored content and semantic identity separately from regenerated export metadata. Re-export from a newly created draft reports that draft’s actual source revision.
Validation and API behavior
Schema validation proves document structure. Owner validation proves references, graph integrity, catalogue membership, allowed bindings and policy constraints. Neither proves a deployment happened.
| Check | Diagnostic location and required result |
|---|---|
| Unknown field or wrong type | The offending property’s JSON pointer; reject rather than silently drop it. |
| Duplicate node, dangling edge or cycle | The affected node/edge pointers; no draft is persisted on invalid import. |
| Tag-only artifact or unknown digest | The artifact field pointer; require an allowed immutable catalogue subject. |
| Unknown extension version | /pipeline/operations/<index>/extension; reject unknown catalogue versions before draft creation. |
| Known extension unavailable on the selected target | The same operation pointer plus target/report context. DPP-057 admission determines availability; denied is blocked, stale/unreported is unknown. |
| Missing/foreign environment, target, provider or artifact | Its field pointer and reference class; preserve tenant authorization and disclose no foreign record. |
| Secret value or policy-locked edit | The field pointer and reason without echoing secret bytes. Reject the input; do not sanitize it into an accepted draft. |
| Unavailable reference owner | Report owner unavailability separately from an invalid or missing reference; do not invent a successful resolution. |
Validate and normalize do not publish, approve, dispatch or mutate a target. Export supports both draft and published revisions. Import validates first and creates a draft through the existing owner’s authorization and revision boundary. A published revision is not changed in place.
Keep the current RO release route family. Exact operation URLs, transport/content types, request limits, error envelope and concurrency token belong to the DPP-002/DPP-056 API implementation; they are not advertised as existing routes here. Reuse current tenant/resource access enforcement. Never trust an imported x-stellaops block as an access grant or current revision token.
Generation and required verification
Generate docs/modules/release-orchestrator/schemas/release-definition.v1.schema.json from the DPP-002 owner model and descriptor contracts. Check committed versus generated bytes in the OpenAPI truthfulness lane. Select the JSON Schema dialect and generator with the owner model; this draft does not introduce a generator dependency or hand-maintained schema.
The implementation corpus belongs in src/__Tests/corpus/release-definitions/:
| Fixture group | Required assertion |
|---|---|
| Minimal valid document; two services/two plugins | Export → edit → validate → import as draft → re-export preserves every declared authored field and expected graph/bindings. |
| Semantic edit; layout-only edit; reordered JSON; equivalent YAML | Semantic edits change the shared semantic identity; layout/export provenance/format-only edits do not. Ordered operation changes remain semantic. |
| Inherit/reset; explicit false/zero; descriptor-permitted empty values | Owner state and provenance survive round-trip without changing meaning. |
| Unknown property/schema revision, duplicate node, dangling edge, cycle | Field-level JSON-pointer rejection; invalid imports create no draft. |
| Plaintext secret, tag-only artifact, unknown extension version, locked field | Rejection before persistence, with no secret bytes in response/log/evidence. |
| Denied/stale/unreported target capability; unavailable reference owner | Preserve blocked, unknown and unavailable outcomes; no implicit admission or fallback. |
RO integration tests must exercise the real provider and persistence path, including export of published content and tenant/resource denial. DPP-059 consumes the generated schema for its person/agent conformance work; design examples cannot close that runtime acceptance.
Source verification
Verified against commit 9402084fa543649e74d2bf1b005774febad640b4 on 2026-10-20, source only. The current Release model contains component membership and lifecycle data. The ReleaseManifest contains finalized component/plugin artifacts. Neither supplies the complete DPP-002 typed authoring graph/configuration model. The release endpoint registration and managed DTO serve the existing release lifecycle.
Recheck those files and the committed RO OpenAPI. The review found the collection and detail paths under /api/v1/release-orchestrator/releases as positive controls, with no definition export/import/validate/normalize path. Re-run: rg -n 'Map(Get|Post|Patch|Put|Delete)|ManagedReleaseDto' src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Endpoints/ReleaseEndpoints.cs, then inspect the release-family paths in docs/modules/release-orchestrator/openapi/v1.json. These are source/document observations, not a live deployment probe.