Specification

Status: Draft · Spec version: 0.6 · Format version: workfile/1

Workfile is an engine-independent format for workflows. A Workfile is one document in that format, and it holds one workflow. A Workfile calls connectors and actions that a catalog publishes. A connector manifest declares each action’s argument schema and its operational behavior: error classification, retry policy, and idempotency. This document defines that manifest format as well.

Workfile follows a single-assignment model. Steps are referenced by id, and results are immutable. The grammar is small, and each construct has one representation over a restricted YAML subset. A Workfile is therefore statically checkable, and a tool can generate one mechanically.

Scope and conformance

What this specification defines

• the Workfile document format and its serialization;
• the expression language and the core filter set;
• the connector manifest format, the filter package manifest format, and the schema overlay format;
• the type system, the error vocabulary, and the trigger kinds;
• the static validation rules that every implementation applies before execution;
• the execution semantics, the recording obligations, and the replay guarantee;
• the conformance levels and the capability names.

What this specification does not define

This standard defines no vendor connector. The standard library defines the canonical connectors and filter packages of the reserved namespaces, and is part of this standard. Beyond the library, this standard defines no connector, no action, and no event.

This standard defines no execution strategy. An implementation can compile a Workfile to an intermediate form, interpret it directly, or lower it onto a host engine.

This standard defines no storage format for a run record, no wire protocol, and no service address.

Conformance targets

An implementation conforms at one of three levels — Validator, Executor, or Durable — and with a declared capability set. The conformance rules state the full conditions.

Requirements are attributed by subject:

• A requirement about parsing, resolution, or validation binds every level.
• A requirement about executing a step, calling an action, or recording an outcome binds Level 2 and Level 3.
• A requirement about suspension, resumption, or replay binds Level 3.

Requirement terms

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174. These words have their normative meaning only when they appear in uppercase.

The word “can” states a capability, and “cannot” states its absence. Neither grants nor withholds permission.

Normative and informative content

The pages of this specification, its annexes, the error code registry, the standard library, and the conformance suite are normative. The overview, the construct status page, and the changes page are informative, as is every document outside this specification. An informative document never states a requirement, and never changes one.

Examples, tables marked as illustrative, and paragraphs that begin with “Note:” are informative. An example never adds a requirement. Where an example and a requirement disagree, the requirement governs and the example is a defect.

Classes of behavior

This document assigns every behavior to one of three classes.

• Specified. The behavior is stated here or in the conformance suite. Every conforming implementation produces it.
• Implementation-defined. The implementation selects the behavior and MUST document its selection. Diagnostic presentation, the storage of a run record, and the scheduling order of concurrent work are implementation-defined.
• Unspecified. More than one behavior is permitted, and an implementation need not document its selection. The order in which independent branches of a parallel step contact external systems is unspecified.

This standard defines no undefined behavior. Every construct produces one of the outcomes that this specification names, or an evaluation fault, or a validation error.