Specification

Revision 0.2.0 (2026-08-28)

Copyright 2026 by Ben Slavin

Abstract

The Workfile Standard defines a declarative workflow language designed to support both lightweight and durable execution, as well as a manifest format for declaring the connectors and actions that workflows can use.

Workfile lets authors describe their intended work in a compact, portable, and readable form, while a runtime engine executes it using the declared connectors.

Foundations

• Introduction to Workfile — The goals and design principles of the Workfile Standard.
• Scope — What the Standard defines, what it leaves to deployments, and its optional features.
• Prior Art — The languages, standards, and systems that informed Workfile.
• Terminology — The defined terms used throughout the specification.
• Conformance and Requirement Language — Normative language, dependencies, behavior classes, and requirement identifiers.

Workfile Core

• Workfile Format Overview — The document model, execution model, constructs, and optional features at a glance.
• Serialization — The restricted YAML subset and document processing rules.
• Data Model — Workfile values, types, comparison, conversion, strings, and time values.
• Workfile Documents — Document structure, names, bindings, steps, modifiers, and triggers.
• Expressions and Templates — Expressions, interpolation, built-in filters, templates, and evaluation faults.
• Workflow Constructs — Values, branching, iteration, waiting, calls, and termination.
• Execution Semantics — Run lifecycle, outcomes, failure, retry, ambiguity, and scheduling variation.

Implementation

• Validation Model and Capabilities — Static validation, diagnostics, capabilities, and deployment support.
• Security Considerations — Credentials, untrusted inputs, resource access, code, and agents.
• Conformance — Conformance targets, traceability, claims, limits, and capability obligations.

Catalog and Manifests

• Connector Manifest Overview — How connectors, actions, connections, catalogs, and manifests fit together.
• Connector Manifests — Connector manifest structure and its action, trigger, overlay, and execution contracts.
• Filter Package Manifests — The manifest format for extension filters and their fixtures.
• Catalog and Packaging — Namespaces, references, resolution, pinning, digests, and extensions.

Capabilities and Profiles

• Scheduled, External-Event, and Polling Initiation — Optional initiation capabilities for schedules, external events, and polling.
• Standard Library — Canonical filter packages and connector definitions.
• Stateful Workflow Profile — State documents, transitions, correlation, and entry steps.
• Durable Execution Profile — Suspension, recovery, compensation, cancellation, and durable history.
• Replay Profile — Reconstruction, re-evaluation, and continuation from recorded history.
• Run Records Capability — Inspection of retained runs: record identity, the record document, and its operations.
• Agent Execution Capability — Bounded model delegation through wf.agent.

Reference

• Versioning the Standard — Revisions, compatibility, transitions, errata, and version selection.
• Syntax Reference — The collected grammar for Workfile expressions and type expressions.
• Registries — Standard codes, capabilities, profiles, namespaces, and reserved names.
• Companion Publications — The status and authority of schemas, suites, guides, and registry artifacts.