Definition syntax
A Definition is one YAML object describing ordered Action steps. For a walkthrough, see Build a Definition.
Top-level fields
| Field | Requirement |
|---|---|
apiVersion | Required; pyplines/v1 |
kind | Required; Definition |
name | Required lowercase alphanumeric name with hyphen-separated segments; maximum 64 characters |
description | Optional descriptive string |
inputs | Optional map of named input declarations |
steps | Required list of 1–256 ordered steps |
Names are not silently normalized. Unknown fields, YAML anchors/aliases, multiple documents, and documents larger than 1 MiB are rejected. Definitions do not contain approval state, runtime identities, execution status, or server database IDs.
Input declarations
Each input declares type: string, boolean, integer, number, object, or array. Optional fields are required, default, enum, and description.
inputs:
service:
type: string
required: true
description: Service to inspect
mode:
type: string
default: inspect
enum: [inspect, repair]
Input and secret identifiers match [A-Za-z_][A-Za-z0-9_-]{0,63}. The declaration above is a fragment; include it in a complete Definition before validation.
Step fields
| Field | Requirement |
|---|---|
name | Required unique lowercase hyphenated name, maximum 64 characters |
description | Optional descriptive string |
uses | Required action-name@version; registry and prefix come from the Environment |
when | Optional whole expression producing a boolean |
with | Input values matching the Action's captured contract |
The step's name is its stable reference in expressions, Run responses, logs, and approval decisions. Put human-readable explanatory text in description:
steps:
- name: inspect-service
description: Check the service before deciding whether to restart it
uses: inspect-service@2026.10.1
The pyplines/v1 contract requires name; the former id field is rejected, including when supplied alongside name. Update existing Definitions and use matching platform and tooling releases. Previously persisted Definitions and Runs are not migrated by this contract update.
References and expressions
| Reference | Resolves to |
|---|---|
inputs.NAME | A supplied or defaulted Run input |
context.NAME | Public Environment context |
secrets.NAME | A versioned Environment secret |
steps.NAME.outputs.NAME | A named output from an earlier step |
steps.NAME.status | An earlier step's state, including succeeded or skipped |
Wrap expressions in ${{ ... }}. A whole expression preserves JSON types. Embedded interpolation accepts only scalar values. Conditions support comparisons and boolean operators, not functions, loops, or splats.
Only earlier steps may be referenced. A skipped step has no outputs; missing outputs block preparation rather than resolving to null. A false when is evaluated before resolving the skipped step's inputs.
Secret references must occupy an entire input value. They cannot appear in conditions or embedded interpolation. Sensitive schemas and secret-tainted output bindings make the receiving step private.
Validation stages
| Stage | What is checked |
|---|---|
Local pyplines validate | Document structure |
| Deployment | Authoritative expressions, Action availability, contracts, and pinned images |
| Step preparation | Resolved runtime values, context, secrets, and policy requirements |
An accepted Definition cannot guarantee that an external service will accept credentials or that an Action's side effects are reversible. Those behaviors belong in the Action's operational contract.