@zeqqat/workflow-schema

The workflow DSL and its structural validation, as Zod schemas.

A workflow is a JSON document: named steps, their inputs and declared outputs, retries, polling, branching, parallelism and compensation. This package is the definition of what that document may contain, and the check that a given one conforms. It is isomorphic — no filesystem, no database, no network — so the same validation runs in a CLI, in a server route, and in a browser.

Part of Zeqqat, which exposes declared workflows as MCP tools. It is published separately because two things need it independently: the @zeqqat/mcp CLI, which loads workflows off disk, and the Zeqqat registry, which validates them on publish.

Install

npm install @zeqqat/workflow-schema

Use

import { WorkflowDefinitionSchema, validateWorkflowStructure } from "@zeqqat/workflow-schema";

const result = validateWorkflowStructure(JSON.parse(raw));
if (!result.success) {
  // every problem, each with the path it came from
  console.error(result.errors);
} else {
  result.workflow; // typed WorkflowDefinition
}

Validation is structural and runs entirely in process: the Zod schema, duplicate step ids, unknown step references, and the three-part calls convention. It never reaches the network, so it is safe to call from a browser.

WorkflowDefinitionSchema is the Zod schema itself, for when you want to parse rather than check, or to compose it into a larger schema.

name and description are required on every workflow. name is the snake_case identifier an agent calls; description is the only text a model reads before choosing the tool, so it is load bearing rather than documentation.

License

Apache-2.0