Space Registry API: schemas
The request and response bodies of the operations in this API.
CreateSpaceDto
| Property | Type | Required | Description |
|---|
allowClassificationBelowParent | boolean | no | Privileged policy flag. When true, permits PERSISTING a classification strictly below the inherited floor. Resolution is a monotone join, so such a value can never lower the effective classification — the flag only suppresses the fail-fast that says so. |
classification | DataClassification | no | Own data classification. MUST be >= the INHERITED floor (the join over the ancestor refs) unless allowClassificationBelowParent is set. |
displayName | string | yes | Human-readable label for this Space. |
labels | map of string | no | |
ref | string | yes | Canonical xema:// Space URI to create. |
DataClassification
The classification DECLARED on this ref.
Type: one of "public", "internal", "confidential", "secret", "regulated"
DisableResourceRoleBindingDto
| Property | Type | Required | Description |
|---|
ownerSpaceRef | string | yes | The owner space this refusal is stated AT — the same <fence>::<SpaceRef> form a binding uses. Stated at a space and inherited downward from there, exactly as a pin is, so a project may refuse a role its organisation has pinned. |
roleKey | string | yes | The role being refused, as <resourceKind>.<role>. Validated by the same constraint a binding uses, so a role that cannot be bound cannot be refused either. |
EffectiveSettingDto
| Property | Type | Required | Description |
|---|
clampedBy | SettingScopeRefDto | no | The rung that narrowed a nearer statement. |
configured | boolean | yes | Did anybody state a value in the chain? false means the declarer default is served. |
effectiveValue | boolean or integer or string | yes | The effective value, at rest (a duration is seconds). |
inheritancePath | array of SettingResolutionStepDto | yes | Every rung considered, closest-first. |
parameterKey | string | yes | |
source | ParameterSourceKind | yes | |
statedAt | SettingScopeRefDto | no | The scope whose statement decided it. |
ExactRevisionSelectorDto
| Property | Type | Required | Description |
|---|
contentHash | string | yes | |
kind | one of "exact" | yes | |
revisionId | string | yes | |
GrowthGateDto
| Property | Type | Required | Description |
|---|
enabled | boolean | no | False closes this action to everyone. Absent leaves it open — absence is the resting state, not a denial. |
minimumOrgRole | one of "org_owner", "org_admin", "org_member" | no | Minimum organization role. Absent means every member satisfies it. |
restrictedToGroupIds | array of string | no | Restrict to members of these identity groups. Absent or empty means no group restriction was stated — it never means "nobody". |
MemberShellModeOverrideDto
| Property | Type | Required | Description |
|---|
groupId | string | yes | |
mode | one of "full", "portal-focused" | yes | |
OrgAppThemeDto
| Property | Type | Required | Description |
|---|
appTheme | string or null | yes | The stated theme id, or null for no built-in pick (the default theme, or the org brand when locked). An opaque kebab-case id the frontend owns: this service checks its shape, never whether the theme exists. |
configured | boolean | yes | False when this organization states neither a theme nor a lock: the frontend applies its default theme. Unconfigured is an answer, never a 404. |
locked | boolean | yes | True when members may not override the theme personally. With appTheme: null it locks members to the org brand with no built-in pick. |
updatedAt | string (date-time) or null | yes | When the theme was last stated; null when none is stated. |
updatedByActorId | string or null | yes | Who last stated the theme; null when none is stated. |
OrgAppThemeDtoDataEnvelope
OrgExperienceSettingsDto
| Property | Type | Required | Description |
|---|
configured | boolean | yes | False when this organization has never written an experience policy. |
effectiveShellMode | one of "full", "portal-focused" | yes | THE FIELD A SHELL READS: which mode THIS caller is in, with the org-wide setting, the per-group overrides and the caller's role already applied. Always present — there is always an answer, and an unconfigured org resolves to the behaviour it already has. The fields above are the POLICY an administrator edits; a shell that reads them instead would re-implement this resolution and drift from it. Still presentation only: it grants and withholds nothing. |
memberShellMode | one of "full", "portal-focused" | no | How the shell presents itself to an ordinary member. Absent leaves today's behaviour in place, which is portal-focused for an ordinary member — see effectiveShellMode, which is the field a shell should read. Administrators are never confined. |
shellModeOverrides | array of MemberShellModeOverrideDto | no | Per-group overrides, evaluated in declaration order so a member of two overridden groups gets a deterministic answer. |
unstatedMemberShellMode | one of "full", "portal-focused" | yes | What an ordinary member gets when this organization has stated nothing — the platform default, not a value anyone configured. Published because an administrator looking at an unconfigured policy still needs to know what their members see, and the alternative is every consumer hard-coding a copy of this constant and drifting from it silently. It does NOT depend on the caller: effectiveShellMode is what YOU get, this is what an unconfigured member gets. |
updatedAt | string (date-time) or null | yes | |
updatedByActorId | string or null | yes | |
OrgExperienceSettingsDtoDataEnvelope
OrgGovernanceSettingsDto
| Property | Type | Required | Description |
|---|
configured | boolean | yes | False when this organization has never written a governance setting — the resting state, not an error. |
dataGovernanceGroupId | string or null | yes | Identity group the downgrade approval is addressed to. Required to arm. |
downgradeApprovalQuorum | number | yes | How many distinct members of that group must approve a downgrade. One refusal is always enough regardless of this value. |
downgradeSeparationOfDuties | boolean | yes | When true, LOWERING a Space classification opens a Decision addressed to the data-governance group instead of performing the write. Raising a classification is never affected. |
source | ParameterSourceKind | yes | Where an effective value came from: platform-default (nobody stated it anywhere), stated (the scope being read stated it) or inherited (a less specific scope in the same chain stated it). |
updatedAt | string (date-time) or null | yes | |
updatedByActorId | string or null | yes | |
OrgGovernanceSettingsDtoDataEnvelope
OrgGrowthSettingsDto
| Property | Type | Required | Description |
|---|
allowedCapabilityDomains | array of string | no | Capability domains a grown bundle may use. ABSENT admits every domain (no restriction stated); an EMPTY list admits none (a deliberate statement). The two are different facts. |
allowedConnectorProviders | array of string | no | Connector providers a grown bundle may use. Same absent-vs-empty semantics as allowedCapabilityDomains. |
authoring | GrowthGateDto | no | May members author at their own scope (apps, skills, agents, bundles, personal portals)? Absent = every member. |
configured | boolean | yes | False when this organization has never written a growth policy — the resting state, not an error. Every default below is permissive. |
externalPublishing | GrowthGateDto | no | Publishing beyond the organization. This is a FLOOR: it always opens a Decision and always requires at least the org admin role, at every organization size. Configuration can only make it stricter. |
internalPublishReviewQuorum | number | no | Absent = internal org publishing needs no review. Setting it ADDS a Decision with this quorum. Absent is an answer, not a quorum of zero. |
publishToOrg | GrowthGateDto | no | May a member publish their OWN grown artifact org-wide? Absent = every member, with NO approval step: promoting what you built is a share, not an acquisition of new authority. |
updatedAt | string (date-time) or null | yes | |
updatedByActorId | string or null | yes | |
OrgGrowthSettingsDtoDataEnvelope
OwnerQualifiedInstanceTargetDto
OwnerQualifiedRevisionTargetDto
OwnerSpaceFence
Type: one of "global", "tenant"
ParameterSourceKind
Where an effective value came from: platform-default (nobody stated it anywhere), stated (the scope being read stated it) or inherited (a less specific scope in the same chain stated it).
Type: one of "platform-default", "stated", "inherited"
ParameterStepOutcome
What this rung did: silent (declared nothing), decided (its value IS the effective one — exactly one rung ever is), shadowed (it declared something and something else decided).
Type: one of "silent", "decided", "shadowed"
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"
ReleaseChannelRevisionSelectorDto
| Property | Type | Required | Description |
|---|
channel | string | yes | |
kind | one of "release-channel" | yes | |
ResolvedResourceRoleBindingResponseDto
| Property | Type | Required | Description |
|---|
ambiguousDefaultProviders | array of string | no | Every biome shipping a default for this role, when more than one does. Present only for ambiguous-default. ALL of them, never the first: the platform has no authority to rank one biome opinion above another's, so the list IS the answer and the choice is a person's. |
binding | ResourceRoleBindingResponseDto | no | Present only when configured. Carries the space the winning binding was stated at, which is what makes an inherited answer explicable. |
configured | boolean | yes | False when no binding is in force anywhere on the ladder. That is an ANSWER, not an error — the owner has stated nothing, and a consumer that wants a fallback states it at its own call site. |
effectiveTarget | object | no | The target actually IN FORCE, whatever produced it — the explicit binding's target, or the managed default's. Present for explicit and managed-default and absent for the other three, because those three have no answer rather than an answer the consumer has to assemble. It exists so a caller that only needs "what runs" reads ONE field instead of branching on source and then picking a different field per arm — which is the branch that goes stale when a sixth source is added. |
managedDefaultProvider | string | no | The biome answering for this role, as an xema:// space URI. Present only for managed-default. A surface that says an answer came from somewhere must be able to say WHERE, or the organisation cannot tell whose default it is about to override. |
source | ResourceRoleResolutionSource | yes | Which authority produced this answer. explicit — the organisation stated it. managed-default — the biome that owns the role ships it and the organisation has stated nothing. disabled — the organisation stated that nothing plays this role. none — nobody has stated anything and no biome ships a default. ambiguous-default — two or more biomes ship a default and the platform has no authority to rank them, so a person must choose. |
ResolvedResourceRoleBindingResponseDtoDataEnvelope
ResourceRoleBindingListResponseDto
ResourceRoleBindingListResponseDtoDataEnvelope
ResourceRoleBindingResponseDto
ResourceRoleBindingResponseDtoDataEnvelope
ResourceRoleCatalogueResponseDto
ResourceRoleCatalogueResponseDtoDataEnvelope
ResourceRoleDeclarationResponseDto
| Property | Type | Required | Description |
|---|
biomeId | string | no | The biome that declared it, when a biome did. Absent for a system seed. |
biomeVersion | string | no | The version of that biome at the time it was declared. |
description | string | yes | What choosing a resource for this role DOES, in the reader’s words. An administrator picking an agent for a role they cannot picture is the failure a settings surface exists to end. |
ownerSpaceRef | string | yes | The space that OWNS this declaration — xema://biomes/<id> for a biome-contributed role, xema://system for a platform seed. Derived from the contribution owner; never authored. |
resolvedAtSpaceKinds | array of one of "system", "org", "project", "app", "session", "biome", "user" | yes | The space tiers a CONSUMER resolves this role at — NOT where a binding may be stated (a binding may be stated anywhere on the ladder and is inherited downward). A surface reads this to tell an administrator the truth about what they are stating, per role, instead of presenting identical controls with different real behaviours. |
roleKey | string | yes | The STABLE identifier a binding names, as <resourceKind>.<role>. It survives a re-implementation of the thing behind it, so it encodes no biome id, route or service name — a key that moved would silently invalidate every binding that names it. |
title | string | yes | The heading a person reads on a settings surface. |
ResourceRoleOwnerSpaceRefDto
ResourceRoleResolutionSource
Which authority produced this answer. explicit — the organisation stated it. managed-default — the biome that owns the role ships it and the organisation has stated nothing. disabled — the organisation stated that nothing plays this role. none — nobody has stated anything and no biome ships a default. ambiguous-default — two or more biomes ship a default and the platform has no authority to rank them, so a person must choose.
Type: one of "explicit", "managed-default", "disabled", "none", "ambiguous-default"
ResourceRoleSpaceRefDto
| Property | Type | Required | Description |
|---|
appId | string | no | |
biomeId | string | no | |
classification | DataClassification | no | |
orgId | string | no | |
path | string | no | |
projectId | string | no | |
sessionId | string | no | |
tier | SpaceKind | yes | |
userId | string | no | |
RevisionTargetDto
SetResourceRoleBindingDto
| Property | Type | Required | Description |
|---|
expectedRevision | number or null | no | An optional precondition on the key's current revision (a live binding's, else its tombstone's). null means "create only if this key has no live binding and no tombstone" (never stated; an unset key keeps a tombstone, so it is refused); a number means "only if the key is at exactly this revision". A mismatch is refused with 409 RESOURCE_ROLE_BINDING_REVISION_CONFLICT, checked before the idempotent no-op, and nothing is written or recorded. Absent: the write is an unconditional upsert. |
ownerSpaceRef | string | yes | The owner space this binding is stated AT, as <fence>::<SpaceRef>. A binding at org space governs every project in that org unless the project states its own. |
roleKey | string | yes | The role, as <resourceKind>.<role>. The kind half must match the target's own resource kind — a binding whose key and target disagree is refused, so no consumer has to decide which to believe. |
target | object | yes | The kernel OwnerQualifiedRevisionTarget. Owner qualification is mandatory: nothing downstream ever infers an owner from precedence. |
SettingDefinitionDto
| Property | Type | Required | Description |
|---|
definition | object | yes | The stamped setting definition (title, value type, constraints, default, declarable tiers, merge). |
key | string | yes | |
namespace | string | yes | |
SettingDefinitionListDto
SettingDefinitionListDtoDataEnvelope
SettingResolutionDto
SettingResolutionDtoDataEnvelope
SettingResolutionStepDto
SettingScopeRefDto
| Property | Type | Required | Description |
|---|
kind | string | yes | The scope kind (SpaceKind value). |
ref | string | no | The Space ref of the scope. |
SettingTargetDto
| Property | Type | Required | Description |
|---|
key | string | yes | The setting key, <namespace>:<name>@<major>. |
scope | string | yes | The Space ref the value is stated at (xema://system, an org or a project). |
SettingUnavailableReason
Type: one of "definition-absent", "definition-retired"
SettingValueDto
| Property | Type | Required | Description |
|---|
key | string | yes | |
scope | string | yes | |
updatedAt | string (date-time) | yes | |
updatedBy | string | yes | |
value | boolean or integer or string | yes | The value as stored, at rest. |
SettingValueDtoDataEnvelope
SpaceAncestorsDto
| Property | Type | Required | Description |
|---|
ancestors | array of SpaceDto | yes | Persisted ancestor Spaces, closest-first (self at index 0), up to System. |
refUri | string | yes | The Space URI that was resolved. |
SpaceAncestorsDtoDataEnvelope
SpaceClassificationDto
| Property | Type | Required | Description |
|---|
clampedByRefUri | string or null | no | The ANCESTOR whose floor overrode a declaration this ref itself made — Law 9's "which override decided this". Null when nothing was taken away, including when this ref declared nothing. |
classification | DataClassification or null | no | Effective classification (the join over the ancestor chain). Null when nothing in the chain declares one. |
configured | boolean | yes | Did ANYBODY in the chain declare a classification? A different fact from what the value is: false means "nobody has armed this", which a UI must not present as "this is public". |
inheritancePath | array of SpaceClassificationStepDto | yes | Every rung considered, CLOSEST-FIRST with the ref itself at index 0, silent rungs included. |
refUri | string | yes | The Space URI that was resolved. |
resolvedFromRefUri | string or null | no | refUri of the Space that contributed the WINNING (most restrictive) value; the closest one where several declare it. |
source | ParameterSourceKind | yes | platform-default (nobody declared anything), stated (this ref declared the winning value), inherited (an ancestor did). |
SpaceClassificationDtoDataEnvelope
SpaceClassificationStepDto
| Property | Type | Required | Description |
|---|
declared | DataClassification or null | no | What THIS rung declares. Null when it declares nothing — the join's identity, and indistinguishable from having no row at all. |
outcome | ParameterStepOutcome | yes | What this rung did: silent (declared nothing), decided (its value IS the effective one — exactly one rung ever is), shadowed (it declared something and something else decided). |
refUri | string | yes | The Space URI of this rung. |
tier | string | yes | The rung's tier (SpaceKind value). Carried so a UI can say "your org's floor" without re-parsing the URI. |
SpaceDto
| Property | Type | Required | Description |
|---|
appId | string or null | no | |
biomeId | string or null | no | |
classification | DataClassification or null | no | Own classification, if explicitly set on this Space. |
createdAt | string | yes | |
displayName | string | yes | |
id | string | yes | Opaque Space id (cuid). |
labels | map of string or null | no | |
orgId | string or null | no | |
projectId | string or null | no | |
refUri | string | yes | Canonical xema:// Space URI. Unique idempotency key. |
sessionId | string or null | no | |
tier | SpaceKind | yes | |
updatedAt | string | yes | |
userId | string or null | no | |
workerInternetEgress | WorkerInternetEgress or null | no | This Space's OWN worker internet-egress declaration. Null when it states nothing — which is not open and not governed. |
SpaceDtoDataArrayEnvelope
| Property | Type | Required | Description |
|---|
data | array of SpaceDto | yes | |
SpaceDtoDataEnvelope
| Property | Type | Required | Description |
|---|
data | SpaceDto | yes | |
SpaceKind
The ref's tier — org or project.
Type: one of "system", "org", "project", "app", "session", "biome", "user"
SpaceWorkerEgressDto
| Property | Type | Required | Description |
|---|
clampedByRefUri | string or null | no | The ANCESTOR whose tighter declaration overrode one this ref itself made. Null when nothing was taken away. |
configured | boolean | yes | Did ANYBODY in the chain declare one? false is an answer ("nobody has narrowed this"), returned with a 200. |
inheritancePath | array of SpaceWorkerEgressStepDto | yes | Every rung considered, CLOSEST-FIRST with the ref itself at index 0, silent rungs included. |
refUri | string | yes | The Space URI that was resolved. |
resolvedFromRefUri | string or null | no | refUri of the CLOSEST space carrying the winning value. |
workerInternetEgress | WorkerInternetEgress or null | no | The tightest declaration in the chain. Null when nothing in the chain declares one — which states nothing, and must not be read as open or as governed. |
SpaceWorkerEgressDtoDataEnvelope
SpaceWorkerEgressStepDto
| Property | Type | Required | Description |
|---|
declared | WorkerInternetEgress or null | no | What THIS rung declares. Null when it declares nothing. |
outcome | ParameterStepOutcome | yes | silent (declared nothing), decided (its value IS the effective one), shadowed (it declared something and a tighter rung decided). |
refUri | string | yes | The Space URI of this rung. |
tier | SpaceKind | yes | |
UpdateClassificationDto
| Property | Type | Required | Description |
|---|
allowBelowParent | boolean | no | Privileged flag permitting a value strictly below the inherited floor. Audited. |
allowDowngrade | boolean | no | Privileged flag required to LOWER the classification (downgrade). Audited. |
classification | DataClassification | yes | |
UpdateOrgAppThemeDto
| Property | Type | Required | Description |
|---|
appTheme | string or null | yes | The theme id to state (kebab-case, 1..64 characters), or null for no built-in pick. Shape only; the web host validates membership in its theme registry. |
locked | boolean | no | True locks members to appTheme: they may not override it personally. Omitted means false. With appTheme: null it locks members to the org brand with no built-in pick; appTheme: null unlocked returns to the default theme. |
UpdateOrgExperienceSettingsDto
| Property | Type | Required | Description |
|---|
memberShellMode | one of "full", "portal-focused" | no | |
shellModeOverrides | array of MemberShellModeOverrideDto | no | |
UpdateOrgGovernanceSettingsDto
| Property | Type | Required | Description |
|---|
dataGovernanceGroupId | string | no | Identity group the approval is addressed to. decision-api expands it against the identity directory at open time; an empty or unknown group fails the downgrade fast rather than producing an ask nobody can answer. |
downgradeApprovalQuorum | number | no | Approvals required. Defaults to 2. |
downgradeSeparationOfDuties | boolean | yes | Arm (true) or disarm (false) separation of duties on classification downgrades. Arming REQUIRES dataGovernanceGroupId. |
UpdateOrgGrowthSettingsDto
| Property | Type | Required | Description |
|---|
allowedCapabilityDomains | array of string | no | |
allowedConnectorProviders | array of string | no | |
authoring | GrowthGateDto | no | |
externalPublishing | GrowthGateDto | no | May only be made STRICTER than the platform floor (org admin). A looser value is refused rather than silently clamped. |
internalPublishReviewQuorum | number | no | Omit to require no review on internal org publishing (the default). |
publishToOrg | GrowthGateDto | no | |
UpdateWorkerEgressDto
| Property | Type | Required | Description |
|---|
workerInternetEgress | WorkerInternetEgress or null | yes | Whether agent workspaces in this space may open sockets to the public internet. null CLEARS the declaration. The effective mode is the most restrictive of the deployment, this space and its ancestors, the agent and the session — so open here never widens a narrower tier. |
WorkerInternetEgress
The mode DECLARED on this ref.
Type: one of "open", "governed"
WriteSettingValueDto
| Property | Type | Required | Description |
|---|
key | string | yes | The setting key, <namespace>:<name>@<major>. |
scope | string | yes | The Space ref the value is stated at (xema://system, an org or a project). |
value | boolean or integer or string | yes | The value in wire form. It is validated against the definition and refused when out of bounds, never clamped. |