Doppels YAML Schema Reference: Capability, Recipe, Space

All Doppels manifests share a single apiVersion: doppels.so/v1alpha1 and are validated against JSON Schema Draft 2020-12. The YAML you write is a deterministic subset of the full YAML specification: no tags, timestamps, anchors, aliases, or merge keys are permitted. Numbers follow JSON numeric grammar. This constraint ensures that manifests parse identically across every runtime and toolchain that implements the schema, and that diffs stay readable in code review.

Capability schema

A Capability defines the public contract of an automation — what inputs it accepts and what outputs it guarantees. It says nothing about how the work gets done; that responsibility belongs to a Recipe. A Capability can exist without a Recipe, in which case a person fulfills the contract manually.

apiVersion: doppels.so/v1alpha1
kind: Capability

metadata:
  name: greet            # machine-readable name — used in CLI commands
  version: 1.0.0         # semantic version — immutable once published
  displayName: Greet     # human-readable label shown in the UI and CLI output

inputs:
  name:
    type: string
    required: true        # omit or set false for optional inputs

outputs:
  message:
    type: string
  report:
    type: artifact
    mediaType: text/plain  # MIME type — required when type is artifact

Input and output types

Type	Description
`string`	Text value.
`integer`	Whole number within the JSON portable range `[-9007199254740991, 9007199254740991]`.
`number`	Any finite JSON number. Integral values must fall within the same portable range.
`boolean`	Exactly `true` or `false`. No tolerant conversion.
`artifact`	A file. Set `mediaType` to the appropriate MIME type.

All declared outputs are part of the required result. A run that does not produce every declared output is an error.

Recipe schema — `shell` runtime

A Recipe defines how a Capability runs. It declares provides to bind itself to one or more Capabilities, and it lists the ordered steps that produce the required outputs. The shell runtime runs each step’s script in an isolated sh or bash process.

apiVersion: doppels.so/v1alpha1
kind: Recipe

metadata:
  name: greet-shell
  version: 1.0.0

provides: [greet]           # names of the Capabilities this Recipe implements

runtime: shell

requires:
  commands: [echo]          # tools that must be present on PATH before the run starts

defaults:
  approval: never           # never | always | local — applies to all steps unless overridden

steps:
  - id: say-hello
    name: Print greeting
    env:
      NAME: "{{ inputs.name }}"   # inject input into the step environment
    run:
      shell: sh                   # sh or bash
      script: |
        # Use the env var here — never a {{ }} expression inside script
        export MSG="Hello, $NAME!"
    produces:
      message:
        env: MSG                  # captures the value of the exported MSG variable

returns:
  message: "{{ steps.say-hello.message }}"   # maps step result to Capability output

Steps execute in the order they are declared. stdout and stderr are logged but are not results — only values captured via produces become outputs. returns must cover every output declared in every Capability named in provides.

`produces` capture methods

Field	Description
`produces.<name>.file`	Captures a file artifact. The path is relative to the workspace. Supports `{{ }}` expressions.
`produces.<name>.env`	Captures the final value of a named exported environment variable.

`defaults.approval` values

Value	Meaning
`never`	Steps run without asking for approval.
`always`	Every step requires explicit approval before running.
`local`	Approval required only when running locally (not in automated contexts).

Approval is never inferred. Every step resolves its approval policy from defaults.approval or its own approval field.

Recipe schema — `manual` runtime

The manual runtime records a human fulfillment of a Capability. Instead of steps and scripts, it points to a runbook document and collects evidence from the person completing the work.

apiVersion: doppels.so/v1alpha1
kind: Recipe

metadata:
  name: service-check-manual
  version: 1.0.0

provides: [service-status]
runtime: manual

procedure:
  readme: ./service-check-runbook.md    # path to the runbook, relative to workspace

evidence:
  notes:
    type: string                        # additional evidence collected during the manual run

The procedure explains the expected work. Outputs are collected directly according to the Capability contract, and evidence captures any proof-of-completion that the procedure requires beyond the standard outputs.

Space schema

A Space is the configuration boundary for a project. It groups the Capabilities and Recipes discovered by convention within its directory and associates them with an Organization context. Capabilities and Recipes are discovered from the filesystem — they are not enumerated inside the Space manifest itself.

apiVersion: doppels.so/v1alpha1
kind: Space

metadata:
  name: my-project
  displayName: My Project
  labels:
    environment: production

Note that Space has no metadata.version field. Unlike Capabilities and Recipes, a Space represents mutable desired state rather than a published, immutable definition.

YAML rules

These rules apply to all Doppels manifests. The doppels validate command enforces them.

Paths must be POSIX-style and relative to the workspace. No absolute paths (starting with /), no drive prefixes (C:), no backslash separators (\), and no parent-directory segments (..). This keeps manifests portable across macOS, Linux, and Windows.
Never use {{ }} expressions inside run.script. Inject values through the env: block and reference them as normal shell variables ($NAME). This prevents shell injection vulnerabilities.
Quote ambiguous tokens. YAML plain scalars like yes, no, on, off, ~, and date-like strings are interpreted differently by YAML 1.1 and 1.2 parsers. When you intend them as strings, always quote them: "yes", "on", "~".
Comments and block scalars are allowed. Use # for comments and | or > for multiline strings (scripts, runbook paths, etc.).
Prohibited YAML features: tags (e.g. !!str), timestamps, anchors (&anchor), aliases (*alias), and merge keys (<<:). None of these are permitted in any Doppels manifest.

Get Started

Core Concepts

Guides

Agent Skills

Reference

Doppels YAML Schema Reference: Capability, Recipe, Space

Capability schema

Input and output types

Recipe schema — `shell` runtime

`produces` capture methods

`defaults.approval` values

Recipe schema — `manual` runtime

Space schema

YAML rules

​Capability schema

​Input and output types

​Recipe schema — shell runtime

​produces capture methods

​defaults.approval values

​Recipe schema — manual runtime

​Space schema

​YAML rules

Capability schema

Input and output types

Recipe schema — `shell` runtime

`produces` capture methods

`defaults.approval` values

Recipe schema — `manual` runtime

Space schema

YAML rules