Concepts · Workflow schemas

Workflow schemas

A Workflow Schema is the platform's contract for what counts as a workflow. It declares the rules every Workflow Template must obey — required fields, allowed types, gate-unlock grammar, sub-workflow reference rules, and validation logic the platform enforces before a Template is publishable.

Position in the model

Workflows on Esy are defined at three levels of abstraction. The Schema is the highest level — the meta-definition that governs how Templates are authored. Most operators never see the Schema directly; they pick a Template that has already been validated against it.

levelstree

Workflow Schema  (rules)             ← this page
       │
       ▼ a Template satisfies the Schema
Workflow Template  (declared)
       │
       ▼ a Run instantiates the Template
Workflow Specification  (runtime)
       │
       ▼ production executes the Specification
Workflow Run + Artifact

What the Schema declares

Concern	What the Schema specifies
Required fields	The set of fields a Workflow Template must contain to be publishable (id, name, artifactClass, version, cadence, intakeSchema, runtimeSteps, providers, gates, budgetPolicy, artifactSchema).
Allowed types and shapes	For each field, the type and shape it must take. artifactClass is an enum; gates is an ordered list of gate objects; providers is a record mapping step names to provider identifiers.
Gate grammar	The structure of a gate: id, name, type, inputs (ArtifactTypeRefs), outputs (ArtifactTypeRefs), and unlocks (gate ids). Determines what flows between steps.
Artifact schema	The shape of what the workflow produces — its artifactType, files, and metadata. Because the artifact is the workflow’s output, declaring that output is part of declaring the workflow. It is an element of the Schema, parallel to the intake schema at the other end.
Sub-workflow references	How a Template can declare that a step delegates to another Template — including version pinning and intake mapping.
Versioning conventions	How Template versions must be tagged and how runs reference a specific Template version snapshot.
Validation rules	The checks the platform runs before publishing a Template — gate-id uniqueness, unlocks-target existence, ArtifactType registration, provider registration, version format.

Example

An illustrative subset of workflow-schema-v1. The Schema itself is a stable declarative document that the platform reads when validating new Templates.

workflow-schema-v1.json (excerpt)json

{
  "schemaVersion": "workflow-schema-v1",
  "templateRequiredFields": [
    "id",
    "name",
    "artifactClass",
    "version",
    "cadence",
    "intakeSchema",
    "runtimeSteps",
    "providers",
    "gates",
    "budgetPolicy",
    "artifactSchema"
  ],
  "artifactClass": {
    "type": "enum",
    "allowed": ["visual", "video", "research", "knowledge"]
  },
  "gate": {
    "fields": {
      "id": "string (required, unique within template)",
      "name": "string (required)",
      "type": "enum [quality, safety, approval, budget]",
      "inputs": "array<ArtifactTypeRef> (required)",
      "outputs": "array<ArtifactTypeRef> (required)",
      "unlocks": "array<GateId>"
    }
  },
  "artifactSchema": {
    "fields": {
      "artifactType": "ArtifactTypeRef (required, registered)",
      "files": "array<FileSpec> (required)",
      "metadata": "object (shape defined by the ArtifactType)"
    }
  },
  "subWorkflowRef": {
    "fields": {
      "templateId": "string (required)",
      "templateVersion": "string (required, pinned)",
      "intakeMapping": "object (required)"
    }
  },
  "validation": [
    "Every gate id must be unique within the template",
    "Every unlocks reference must point to a gate in the same template",
    "Every artifactSchema must reference a registered ArtifactType",
    "Every provider must be a registered ProviderRef",
    "Template version must be ISO-style date-tagged"
  ]
}

Audience

The Schema is consumed by three audiences, in order of how often they engage with it:

Platform engineers — Author and version the Schema itself. Decide what counts as a valid workflow on Esy. Rarely changes the Schema; when it does, existing Templates either remain on their prior Schema version or migrate.
Workflow designers — Author new Templates that conform to the Schema. Read it as a reference for what fields are required and what shapes are valid.
Operators — Almost never. Operators pick Templates that have already been validated against the Schema. The Schema is platform-internal.

Frequency

One per platform, versioned. The Schema is a singleton across Esy, evolving through explicit versions (workflow-schema-v1, workflow-schema-v2). When the Schema changes, every Template declares which Schema version it conforms to, and the platform routes validation accordingly.

The Schema is the contract. Templates are concrete instances of that contract.

Think of the Schema as a TypeScript language specification, and a Template as a specific interface User { ... } declaration. The language spec defines what an interface can be; an interface declaration is one concrete shape inside that spec. Multiple Templates can satisfy the same Schema, just as many interfaces can be written in TypeScript.

Related concepts

Workflow templates — concrete predesigned workflows that satisfy the Schema.
Workflow specifications — per-run populated instances of a Template.
Runs — durable execution records of a Specification.
Artifacts — the outputs of a Run, with provenance back through Specification, Template, and Schema versions.