Stack Schema Reference
This page is a generated YAML serialization appendix for the typed stack contract. The public API contract is the Rust type and validation model documented at /docs/stack-format; this schema projection exists for tooling and machine-readable checks.
Schema version: https://stackie.dev/schemas/composite-stack/v1.json
Formal specification for stackie stack YAML (v1). A stack file contains exactly one top-level key (the stack name) whose value is a CompositeStack object.
CompositeStack
A named collection of block instances with optional dependency ordering and per-instance overrides. Extra fields (e.g., ‘name’, ‘description’, ‘test’ for integration test harnesses) are permitted — stackie’s serde layer ignores unknown keys.
| Property | Type | Required | Description |
|---|---|---|---|
schema_version | v1 | no | Optional schema version declaration. When present, must match a supported version (currently ‘v1’). |
blocks | map<string, StackBlockNode> | no | Map of block instances keyed by block identifier (e.g., ‘stackie.postgres’, ‘my-api’, ‘gateway.aws’). |
ingredients | map<string, StackBlockNode> | no | Legacy alias for ‘blocks’. Use ‘blocks’ for new stacks. |
stacks | map<string, SubstackReference> | no | Substacks to compose into this stack, keyed by substack name. |
mode | managed | unmanaged | no | Stack management mode controlling port-allocator activation. |
storage_root | string | no | Optional storage root prefix for all block volume paths in this stack. |
At least one of the following must be present:
blocks,ingredients,stacks.
StackBlockNode
A single block instance within a stack. May be null (no overrides) or an object with optional override fields.
Scalar form: null
Object form (variant 2)
| Property | Type | Required | Description |
|---|---|---|---|
path | string | no | Local source directory for first-party blocks (relative to CWD). |
depends_on | array<string> | no | Names of blocks that must start before this block. |
consumes | array<string> | map<string, ConsumesEntry> | no | Port-consumption declarations. Accepts list of block names or map of alias → consumes entry. |
provider | string | no | Provider selector (e.g., ‘aws’, ‘gcp’). Required for gateway.* blocks. |
name | string | no | Display name for this block instance. |
version | string | no | Block version override. |
environment | map<string, string> | no | Environment variables for this block. |
serves | map<string, PortConfig> | no | Ports served by this block. |
ports | map<string, PortConfig> | no | Legacy alias for ‘serves’. |
vars | map<string, string> | no | String variables accessed as ${vars.NAME}. |
paths | map<string, string> | no | Named filesystem paths accessed as ${paths.NAME}. |
hooks | any | no | Lifecycle hooks (opaque JSON; stackie deserializes at runtime). |
init | array<any> | no | Additional init operations to run after block’s own init. |
command | string | array<string> | no | Command to run (string or array of strings). Required for first-party blocks. |
tools | array<any> | no | Runtime tool requirements (e.g., [{node: '20'}, {python: '3.11'}]). |
health_check | HealthCheck | no | Health check configuration. |
emoji | string | no | Display emoji for the topology view. |
sandbox | boolean | no | Sandbox opt-out for first-party blocks (true = sandboxed, the default). |
bindings | map<string, string> | no | FaaS dev-mode bindings: maps a function name to a user-defined block name. Only meaningful on gateway.* blocks. When present, the Gateways runtime resolves the block port at startup and routes invocations to that block instead of creating a new container. |
ConsumesEntry
A single port-consumption descriptor. Accepts string shorthand or object form.
Scalar form: string
Object form (variant 2)
| Property | Type | Required | Description |
|---|---|---|---|
port_type | string | no | |
block_override | string | no |
PortConfig
Port configuration. Accepts a bare integer (the port number), a string (for ${vars.X}-interpolated values resolved later at runtime), or an object with optional port/type/protocol plus extension fields like expose/label/value.
Scalar form: integer
Scalar form: string
Object form (variant 3)
| Property | Type | Required | Description |
|---|---|---|---|
port | integer (min: 0, max: 65535) | string | no | |
value | integer (min: 0, max: 65535) | string | no | |
type | string | no | |
port_type | string | no | |
protocol | string | no | |
expose | boolean | no | |
label | string | no |
HealthCheck
Health check configuration (HTTP, TCP, command, or process-based).
No properties defined (opaque object — validated at runtime).
SubstackReference
Override settings for a substack included via the ‘stacks:’ field.
| Property | Type | Required | Description |
|---|---|---|---|
vars | map<string, string> | no | |
ports | map<string, map<string, PortConfig>> | no | |
storage_root | string | no |