Xema Shell API: schemas
The request and response bodies of the operations in this API.
ShellCommandDescriptorDto
| Property | Type | Required | Description |
|---|
authorityEffect | one of "none", "expanding" | no | Whether invoking the command grants, expands or reassigns authority. Joined monotonically with the shared classifier the capability router runs, so a declaration may raise it and can never switch the self-escalation guard off. |
examples | array of string | yes | Example invocations. |
name | string | yes | Command name (the verb invoked as xema <name>). |
outputSchema | object | no | JSON Schema reference for the structured output, when declared. Carried verbatim from the kernel JsonSchemaRefStub ({ "$ref": string }); the public help endpoint never resolves it. Modelled as a free-form object because a literal $ref-keyed property collides with the JSON Reference keyword in the generated OpenAPI schema. |
reach | one of "owner", "integration", "platform" | no | How far outside the invoking subject the command reaches, when it reaches further than the caller. Absent means owner. Joined monotonically with the platform derivation: it may raise, never lower. |
relatedConcepts | array of string | yes | Related XemaObjectRef concept strings (e.g. xema://concept/biome). |
requiredCapabilities | array of string | yes | CapabilityRef strings the command requires (enforced by xema-capability-router, not here). |
requiredZones | array of string | no | Environment slugs the command may run against (e.g. project, sandbox). |
requiresApproval | boolean | yes | Whether invoking the command requires explicit human approval, projected verbatim onto its capability descriptor. |
riskTier | one of "low", "medium", "high", "critical" | yes | Risk tier of invoking the command, projected verbatim onto its capability descriptor. low is what admits a capability to the org-admin baseline bundle, so it is a declaration, never a default. |
safeForAgents | boolean | yes | Whether the command may be handed to an autonomous agent unattended. ADVISORY: nothing enforces it today — measured 2026-09-06, the identifier occurs in zero files under biomes/xema-capability-router, against a control of 11 files for requiresApproval, which the router does read. This description previously claimed the router enforced it. |
sideEffects | string | yes | What running the command changes — the sentence a caller reads before invoking. Projected verbatim onto the capability descriptor. |
summary | string | yes | One-line human summary of what the command does. |
syntax | string | yes | Usage syntax string (e.g. xema help [<command>]). |
ShellHelpCommandResponseDto
ShellHelpCommandResponseDtoDataEnvelope
ShellHelpListResponseDto
| Property | Type | Required | Description |
|---|
commands | array of ShellCommandDescriptorDto | yes | Every built-in Shell command descriptor, served verbatim from the registry. |
ShellHelpListResponseDtoDataEnvelope
ShellParseResponseDto
| Property | Type | Required | Description |
|---|
name | string | yes | |
options | object | yes | |
positional | array of string | yes | |
raw | array of string | yes | |
ShellParseResponseDtoDataEnvelope
ShellRunDenialDto
| Property | Type | Required | Description |
|---|
capability | string | yes | |
code | string | yes | |
environment | string | yes | |
reasons | array of ShellRunDenialReasonDto | yes | |
suggestions | array of object | yes | |
ShellRunDenialReasonDto
| Property | Type | Required | Description |
|---|
code | string | yes | |
detail | string | yes | |
ShellRunDiagnosticDto
| Property | Type | Required | Description |
|---|
code | string | yes | Structured diagnostic code (closed per handler). |
level | one of "info", "warn", "error" | yes | |
message | string | yes | |
ShellRunRequestDto
| Property | Type | Required | Description |
|---|
argv | array of string | yes | Structured argv array. Never a raw string — no shell eval anywhere in the platform. |
cwd | string | no | XVFS path the command runs against — passed through to handlers that take a cwd. |
outputMode | one of "json", "human" | yes | Closed-set output mode. Agent invocations through the shell:run@1 capability force json. |
stdin | object | no | Optional structured stdin for commands that take it. |
ShellRunResponseDto
| Property | Type | Required | Description |
|---|
auditId | string | yes | |
denial | ShellRunDenialDto | no | |
diagnostics | array of ShellRunDiagnosticDto | no | |
exitCode | number | yes | Process-style exit code (0 = success). |
result | object | no | Structured handler output (shape varies per command). |
status | one of "allowed", "denied" | yes | |
ShellRunResponseDtoDataEnvelope
SpaceKind
Ownership tier (system | org | project | app | session | biome | user).
Type: one of "system", "org", "project", "app", "session", "biome", "user"
SpaceRefDto
| Property | Type | Required | Description |
|---|
biomeId | string | no | |
orgId | string | no | |
projectId | string | no | |
tier | SpaceKind | yes | Ownership tier (system | biome | org | project | user). |
userId | string | no | |
XvfsResolvedDto
| Property | Type | Required | Description |
|---|
kind | string | yes | Object kind: open, kebab-case, contributed by the biome that owns the noun. |
payload | object | yes | Kind-specific payload. Schema is supplied by the owning domain contract package. |
ref | string | yes | Canonical xema://... ref this path resolved to. |
scope | SpaceRefDto | yes | |
XvfsResolvedDtoDataEnvelope
XvfsWriteBodyDto
| Property | Type | Required | Description |
|---|
payload | object | yes | Kind-specific payload to write/upsert at the resolved object ref. Schema is owned by the object-registry-api for the resolved XemaObjectKind. |
XvfsWriteResultDto
| Property | Type | Required | Description |
|---|
created | boolean | yes | Whether a new XemaObject was created (true) or an existing one was updated (false). |
ref | string | yes | Canonical xema://... ref that was written. |
XvfsWriteResultDtoDataEnvelope