Distribution API: schemas

The request and response bodies of the operations in this API.

EditionBiomeDto

Property	Type	Required	Description
`displayName`	string	no	Human name from the catalog projection, when the lock carries one.
`id`	string	yes
`installPolicy`	string	no	What a MINIMAL install boots versus a DEFAULT one: `required` \| `default-selected` \| `optional`. Absent on a lock that predates the package model.
`mandatory`	boolean	yes	Force-on: the org cannot disable this biome. A DISTRIBUTION decision resolved per edition, never a property the biome self-declares — the same biome is mandatory in one edition and optional in another.
`origin`	string	yes	Provenance posture — `first-party` or `third-party`.
`services`	array of string	yes	Deployable service names this biome ships. Empty for a biome that ships only web or runtime components — such a biome is a selection unit that never boots a service, which is why a service count is not a biome count.
`storeListed`	boolean	yes	Whether the store lists this biome. Derived by the lock, never by this service.
`target`	string	yes
`tier`	string	yes
`version`	string	yes

EditionBiomeVersionChangeDto

Property	Type	Required
`from`	string	yes
`id`	string	yes
`to`	string	yes

EditionDiffDto

Property	Type	Required	Description
`added`	array of string	yes	In the proposal, not in the running edition.
`removed`	array of string	yes	In the running edition, not in the proposal.
`unchanged`	array of string	yes	In both, at the same resolved version.
`versionChanged`	array of EditionBiomeVersionChangeDto	yes

EditionDto

Property	Type	Required	Description
`biomes`	array of EditionBiomeDto	yes
`contentCoordinate`	string	yes	The resolved lock’s own inputHash. It moves only when the edition’s locks change, so it identifies CONTENT rather than a build. This is the hash itself — the deployment pin spells it `0.0.N-h<hash16>`, and that numbering is the deploy plane’s, not this service’s to invent.
`id`	string	yes
`platformServices`	array of string	yes	Platform service ids the lock binds.
`resolvedAt`	string	no	When the distribution plane RESOLVED this lock — not when this deployment adopted it, and not when this request was served. Optional because the lock schema makes it optional; a lock without one is one nothing can date.

EditionDtoDataEnvelope

Property	Type	Required	Description
`data`	EditionDto	yes

EditionPlanDto

Property	Type	Required	Description
`diff`	EditionDiffDto	no	What changes against the running edition. Absent when the proposal did not resolve — there is nothing to diff, and emitting an empty diff would read as "changes nothing".
`manifest`	object	yes	The manifest an operator commits, verbatim.
`problems`	array of EditionProposalProblemDto	yes
`resolvable`	boolean	yes	False when any problem is present. A plan with problems is never partially applicable — the distribution plane resolves all-or-nothing.
`resolvedBiomeIds`	array of string	yes	Biome ids the proposal would resolve to, sorted. A PREVIEW computed by the runtime preview resolver: tier and origin selectors, exclusions and the transitive `requires` closure are all applied, but the result is not a sealed lock and is not admissible for deployment — the deployable edition is what `xema edition seal` produces. Empty when the proposal is not resolvable; read `resolvable` before reading a count.
`resolvedPlatformServices`	array of string	yes	Platform service names the proposal binds. A biome is a selection unit, not one service — so this is neither a subset nor a superset of the biome list.
`universe`	EditionUniverseDto	yes	The biome set the proposal was resolved against.

EditionPlanDtoDataEnvelope

Property	Type	Required	Description
`data`	EditionPlanDto	yes

EditionProposalDto

Property	Type	Required	Description
`description`	string	no	One-paragraph description of the edition.
`displayName`	string	yes
`exclude`	array of string	no	Biome ids to exclude from the edition.
`id`	string	yes
`include`	array of string	yes	Selectors, in the grammar `xema-distribution.json` uses — `{ biome }` or `{ tier }`, plus the optional installPolicy/mandatory fields. It is NOT a list of ids: three of the four shipped editions are built from `{ tier }` selectors, which a bare id list cannot express at all. Validated by the kernel’s own parseDistribution.
`requiredPlatforms`	array of string	yes	Platforms every image in this edition must serve. Verified at DELIVERY against the real registry, fail-closed — declaring one nothing builds makes the edition loudly undeliverable, never silently single-arch.

EditionProposalProblemDto

Property	Type	Required	Description
`code`	one of `"EDITION_MANIFEST_INVALID"`, `"EDITION_ID_COLLISION"`, `"EDITION_BIOME_UNKNOWN"`, `"EDITION_RESOLVER_REFUSED"`, `"EDITION_LOCK_PREDATES_NEXUS_FACTS"`, `"EDITION_SEED_LOCK_NOT_PLANNABLE"`	yes
`detail`	string	yes

EditionUniverseDto

Property	Type	Required	Description
`biomeCount`	number	yes	How many biomes a proposal may select from here.
`distributionId`	string	yes	The edition whose lock supplied the universe.
`narrowerThanPlane`	boolean	yes	True when the universe is narrower than the distribution plane’s index. Always true for a deployment-side plan — a deployment never carries every biome in the monorepo. Rendered so an operator reads the count knowing what it was drawn from.
`source`	string	yes	Where the universe came from. `running-lock` is the only value today: the edition this deployment runs, which is what the chart mounts.

ProblemActionableBy

Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.

Type: one of "user", "org-admin", "platform", "none"

ProblemDetailsDto

RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	string	yes	SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ProblemFieldIssueDto

Property	Type	Required	Description
`code`	string	no	SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem.
`detail`	string	yes	Prose for logs and developers. A frontend localises from `code` + `params` instead.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for this issue's `code`.
`pointer`	string	yes	RFC 6901 JSON Pointer into the request body. Root is "/".

ProblemRetry

What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.

Type: one of "transient", "after-change", "never"