Operation YAML reference

Field tables below are derived from src/schemas/operation.schema.json, the same schema samaritan validate enforces and samaritan schema exports.

For guides and worked examples see the operation authoring pages; this page is the exhaustive field list.

Operation

Top-level fields of an operation document.

Field	Type	Required	Default	Description
name	string	yes	—	Operation name (min length 1)
version	string	yes	—	Semantic version (e.g., 1.0.0) (pattern ^\d+\.\d+\.\d+$)
description	string	no	—	Operation description
author	string	no	—	Operation author
category	string	no	—	Operation category
overview	object	no	—	Flexible overview/metadata section with custom fields (e.g., Release Date, Release Notes, etc.)
needs	string[]	no	—	Required operation dependencies
uses	string	no	—	Marketplace operation reference
with	object	no	—	Parameters for marketplace operation
environments	object[]	no	—	Environments this operation targets. Each entry declares a name and its variable values; an entry may instead be { uses: <file> } to import an environment manifest wholesale. (min items 1)
variables	object	no	—	Variables shared across all environments (convenience alias of common_variables; common_variables wins on key conflict)
common_variables	object	no	—	Common variables shared across all environments (can be overridden by environment-specific variables)
env_file	string	no	—	Path to .env file for loading variables (lowest priority in variable lookup)
sessions	object	no	—	Named tmux sessions for execution engine (map of session name -> config). ${VAR} in a session name/key is resolved against common variables, so sessions can be derived from e.g. a ticket id.
run	object	no	—	Run-mode configuration for the execution engine
steps	object[]	yes	—	The ordered steps of the operation. An entry may instead be { uses: <file>, with: {...} } to expand the steps of another file inline. (min items 1)
rollback	object	no	—	Operation-level rollback plan, offered as [g] global rollback at any step prompt during a run.
metadata	object	no	—	Provenance for the operation document. Normally populated automatically and embedded in generated manuals rather than authored by hand.

Environment

Entries of environments:. An entry may instead be { uses: <file> } to import an environment manifest wholesale.

Field	Type	Required	Default	Description
name	string	yes	—	(min length 1)
from	string	no	—	Inherit environment definition from manifest
description	string	no	—
variables	object	no	—
targets	string[]	no	—
approval_required	boolean	no	—
validation_required	boolean	no	—
restrictions	string[]	no	—

Step

Entries of steps:. A step may instead be { uses: <file>, with: {...} } to expand the steps of another file inline.

Field	Type	Required	Default	Description
id	string	no	—
name	string	yes	—	(min length 1)
type	automatic | manual | approval | conditional	yes	—
phase	preflight | flight | postflight	no	—	Execution phase of the step
description	string	no	—
command	string	no	—
script	string	no	—	Path to an external shell script (relative to operation file). Content is read and embedded in generated manuals.
instruction	string	no	—
if	string	no	—	Condition for conditional steps
timeout	number	no	—	(min 0)
estimated_duration	number	no	—	(min 0)
env	object	no	—
uses	string	no	—	Path to a file whose steps are expanded inline here (relative to operation file)
with	object	no	—	Variables to pass to the included file (all ${VAR} placeholders must be provided)
variables	object	no	—	Step-scoped variables that override environment and common variables
evidence	object	no	—
continue_on_error	boolean	no	—
needs	string[]	no	—
sub_steps	Step[]	no	—
manual_override	boolean	no	—
manual_instructions	string	no	—
ticket	string | string[]	no	—	Bug/issue ticket references
foreach	Foreach	no	—	Loop/matrix support for repeatable steps
section_heading	boolean	no	—	If true, render as a new markdown heading instead of table row
pic	string	no	—	Person In Charge for this step
reviewer	string	no	—	Reviewer/buddy who monitors and verifies the PIC's work
session	string	no	—	Named tmux session to use for this step (execution engine)
capture	object	no	—	Extract named values from command output for use in later steps
expect	string | Expect config | Expect config[]	no	—	Assert this step's output. String shorthand = expect contains.
verify	string | object	no	—	DEPRECATED - use expect: instead. Backward-compatible shorthand only: a bare string, or an object whose expect key is lifted into expect. EVERY OTHER KEY IS DISCARDED - in particular verify.command: is silently dropped and never runs. There is no separate verification command: a step runs its own command:, and expect is matched against that output. (deprecated)
timeline	string | object	no	—	Expected date/time or duration for this step (string or structured format)
options	object	no	—	Step-level rendering and substitution options
when	string[]	no	—	Conditional rendering: only show this step for specified environments (min items 1)
variants	object	no	—	Environment-specific step overrides (can override any step field except 'when' and 'variants')
rollback	Rollback step[] | Rollback step	no	—	Rollback steps for this step. A rollback step is a full step with the same field surface (see the Rollback step reference). Array format preferred; object format accepted for backward compatibility (parser normalizes to array).
retry	object	no	—
approval	object	no	—

Expect config

Assertion rules used by expect: on a step, sub-step or rollback step.

Field	Type	Required	Default	Description
contains	string	no	—
not_contains	string	no	—
equals	string	no	—
matches	string	no	—
not_empty	boolean	no	—
any_line_contains	string	no	—
no_line_contains	string	no	—
all_lines_match	string	no	—
any_line_matches	string	no	—
no_line_matches	string	no	—
line_count	number	no	—	(min 0)
line_count_gte	number	no	—	(min 0)
numeric_gte	number	no	—
numeric_lte	number	no	—
jsonpath	string	no	—
equals_captured	string	no	—
retry	object	no	—

Rollback step

Entries of a step-level or operation-level rollback.steps: list.

Field	Type	Required	Default	Description
id	string	no	—
name	string	no	—
type	string	no	—
phase	preflight | flight | postflight	no	—	Execution phase of the step
if	string	no	—	Condition for conditional steps
description	string	no	—
command	string	no	—
script	string	no	—	Path to an external shell script whose content is embedded in the manual
instruction	string	no	—
timeout	number	no	—	(min 0)
estimated_duration	number	no	—	(min 0)
env	object	no	—
uses	string	no	—	Path to a file whose steps are expanded inline here as rollback steps (relative to operation file). Same file composition as normal-step uses: — expanded at parse time into a flat list of rollback steps.
with	object	no	—	Variables to pass to the included file (all ${VAR} placeholders must be provided)
variables	object	no	—	Step-scoped variables that override environment and common variables
session	string	no	—	Session to run rollback in (defaults to step session)
pic	string	no	—	Person In Charge of executing this rollback step
reviewer	string	no	—	Reviewer/buddy who verifies this rollback step
continue_on_error	boolean	no	—
needs	string[]	no	—
manual_override	boolean	no	—
manual_instructions	string	no	—
section_heading	boolean	no	—	If true, render as a new markdown heading instead of table row
foreach	Foreach	no	—	Loop/matrix support for repeatable steps
capture	object	no	—	Extract named values from command output for use in later steps
ticket	string | string[]	no	—	Bug/issue ticket references
timeline	string | object	no	—	Expected date/time or duration for this step (string or structured format)
when	string[]	no	—	Conditional rendering: only show this step for specified environments (min items 1)
variants	object	no	—	Environment-specific step overrides (can override any step field except 'when' and 'variants')
retry	object	no	—
approval	object	no	—
evidence	object	no	—
expect	string | Expect config | Expect config[]	no	—	Assert this rollback step's output. String shorthand = expect contains.
verify	string | object	no	—	DEPRECATED - use expect: instead. Backward-compatible shorthand only: a bare string, or an object whose expect key is lifted into expect. EVERY OTHER KEY IS DISCARDED - in particular verify.command: is silently dropped and never runs. There is no separate verification command: a step runs its own command:, and expect is matched against that output. (deprecated)
sub_steps	Rollback step[]	no	—	Nested rollback sub-steps, rendered recursively under this step
options	object	no	—	Step-level rendering and substitution options

Rollback plan

The operation-level rollback: object.

Field	Type	Required	Default	Description
automatic	boolean	no	—	Marks the plan as automatic. Non-interactive execution is NOT implemented - see ROADMAP.md; the plan is still offered interactively.
conditions	string[]	no	—	Human-readable conditions under which this rollback plan should be run
aggregate_step_rollbacks	boolean	no	false	When true, the global rollback also groups every step's own rollback (reverse step order), appended after the explicit steps below. In generated manuals this centralizes per-step rollbacks: each step's inline rollback collapses to a jump-link into the Rollback Plan (which carries the anchor target) and the duplicate Rollback Procedures section is dropped. Lets operators author rollback next to the step it undoes while still seeing/running one consolidated recovery.
steps	Rollback step[]	no	—	Explicit rollback steps, run in the order given

Metadata

Field	Type	Required	Default	Description
created_at	string	no	—	When the operation was created (ISO 8601)
updated_at	string	no	—	When the operation was last modified (ISO 8601)
source	string	no	—	Where the operation originated (e.g. the source file or template it was created from)
git_hash	string	no	—	Git commit the operation was generated from, for traceability

Step sub-objects

evidence

Field	Type	Required	Default	Description
required	boolean	no	—
types	(screenshot | log | command_output | file | photo | video)[]	no	—
results	object	no	—	Environment-keyed evidence results (e.g., { staging: [...], production: [...] })

options

Step-level rendering and substitution options

Field	Type	Required	Default	Description
substitute_vars	boolean	no	true	Substitute ${VAR} in instruction and command (default: true)
show_command_separately	boolean	no	false	Show command in separate section from instruction (default: false)

retry

Field	Type	Required	Default	Description
attempts	number	no	—	(min 1)
delay	number	no	—	(min 0)
backoff	linear | exponential	no	—

approval

Field	Type	Required	Default	Description
required	boolean	no	—
approvers	string[]	no	—
timeout	string	no	—

Foreach

Loop a step over one variable or a matrix of variables.

Field	Type	Required	Default	Description
var	string	yes	—	Variable name to use in iteration (min length 1)
values	any[]	yes	—	Array of values to iterate over (min items 1)

Field	Type	Required	Default	Description
matrix	object	yes	—	Matrix of variables for cartesian product expansion
include	object[]	no	—	Additional specific variable combinations to include
exclude	object[]	no	—	Specific variable combinations to exclude