Workflow configuration reference

Every key of a sanity.workflow.ts config: defineWorkflowConfig, deployments, partitions, resource aliases, reader-model acknowledgement, and runtime blocks.

This page lists every key a sanity.workflow.ts config accepts at Workflows 0.37: the object passed to defineWorkflowConfig, each deployment in its deployments array, and the runtime blocks a deployment, workflow, or effect can carry. It also lists the validation errors the config raises. For what a deployment, partition, and resource alias mean, read Deployments, partitions, and resources. To write and deploy a config step by step, follow Configure and deploy workflow definitions.

A config with two deployments of the quick start's article-review. dev keeps engine documents in the content dataset. production keeps them in a separate dataset and binds the content alias to the dataset its articles live in.

import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
import type {WorkflowDeploymentInput} from '@sanity/workflow-engine'

import {articleReview} from './workflows/article-review'

export const dev = {
  name: 'dev',
  partition: 'dev',
  expectedMinReaderModel: 10,
  workflowResource: {type: 'dataset', id: 'PROJECT_ID.DATASET_NAME'},
  definitions: [articleReview],
} satisfies WorkflowDeploymentInput

export const production = {
  name: 'production',
  partition: 'production',
  expectedMinReaderModel: 10,
  workflowResource: {type: 'dataset', id: 'PROJECT_ID.workflows'},
  resourceAliases: [{name: 'content', resource: {type: 'dataset', id: 'PROJECT_ID.production'}}],
  runtime: {kind: 'function'},
  definitions: [articleReview],
} satisfies WorkflowDeploymentInput

export default defineWorkflowConfig({deployments: [dev, production]})

The CLI imports the module's default export and validates it again with defineWorkflowConfig, so a plain object default export fails at the same point a malformed defineWorkflowConfig call does. Exporting each deployment by name lets scripts, Blueprints, and the Functions generator import the same object.

WorkflowConfigInput is the object you pass to defineWorkflowConfig, imported from @sanity/workflow-engine/define. Every entry in deployments is a WorkflowDeploymentInput.

WorkflowDeploymentInput is the authored shape of one deployment, exported as a type from @sanity/workflow-engine. Annotate a named export with satisfies WorkflowDeploymentInput to check it where you write it and reuse it from configuration, scripts, and Blueprint entry points.

Unknown keys on a deployment are ignored and dropped from the parsed result.

A deployment and a workflow (defineWorkflow) accept RuntimeBlock. An effect accepts EffectRuntimeBlock, which adds the function budget. A workflow inherits its deployment's kind and each effect inherits its workflow's kind; a block at a lower level overrides the inherited value. With no block at any level, the kind is function. The block is authoring metadata: deploy strips it before storing the definition, so changing it creates no definition version. Regenerate and redeploy the runtime after changing it.

Effects with the same name in one deployment must declare the same kind and budget: one effect name has one handler. The generator rejects a mismatch and names both definitions.

defineWorkflowConfig validates its input and returns the parsed shapes below. Read them when you write tooling that loads a config; author with WorkflowConfigInput and WorkflowDeploymentInput.

The return value of defineWorkflowConfig. Every deployment carries a resolved partition, default when the author omitted it, and expectedMinReaderModel may still be missing until a command that submits definitions selects that deployment.

One parsed deployment: name, partition (always set), workflowResource, definitions, and the optional resourceAliases, runtime, and expectedMinReaderModel. A deprecated tag is already migrated to partition. Do not pass it back to an API that requires WorkflowDeploymentInput.

A WorkflowDeployment whose expectedMinReaderModel has been checked against the definitions a command will submit, so the field is a number. The CLI's deploy and definitions diff produce it, and Workflows Blueprint resources require it.

Deploy compares a deployment's expectedMinReaderModel with the highest floor its submitted definitions require. These @sanity/workflow-engine exports compute and check that floor. The rollout that justifies raising the value is in Upgrade Workflows packages.

• requiredDefinitionReaderModel(definitions)(): number

  The reader model a deployment must acknowledge for a batch of definitions: the highest requirement in the batch. The baseline is 4. Role-constrained plural assignment fields need 8. Singular assignment fields, and guards spanning edit and lifecycle id groups, need 9. Required subject, doc.ref, and doc.refs fields, and effect retry policies, need 10. A workflow-level abort block needs 11.

• assertReaderModelAcknowledgement(value, {requiredMinReaderModel, context?})(): asserts value is number

  Throws ReaderModelAcknowledgementError unless value is an integer from requiredMinReaderModel through DATA_MODEL_MAX_READER. context labels the caller in the message and defaults to Deployment.

• DATA_MODEL_MAX_READER(): 11

  The highest acknowledgement the installed engine accepts. Keep deployment acknowledgements as reviewed literals; do not import this constant in place of checking your runtimes.

• requiredReaderModel(documentType, document)(): number

  The oldest engine model that can read one stored definition or instance document. Returns 0 when no governed feature raises the floor.

• requiredModelFeatures(documentType, document)(): readonly DataModelChange[]

  The DATA_MODEL_CHANGES entries whose detectors apply to one stored definition or instance.

• DATA_MODEL_CHANGES(): readonly DataModelChange[]

  The append-only manifest of persisted-model changes. Each entry has id, introducedInModel, minReaderModel, documentTypes, compatibility (additive or reader-floor), applicability, and summary.

ReaderModelAcknowledgementError has kind reader-model-acknowledgement and code WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH, and carries expectedMinReaderModel, requiredMinReaderModel, engineMaxReaderModel, and documentationUrl. Its message, for a deployment named dev that acknowledges 3:

Deployment dev acknowledges reader model 3; the submitted definitions require at least 10, and this writer supports acknowledgements through 11.
Use a reviewed numeric literal in that range. Before raising it, ensure every runtime sharing the workflow resource can read the required model.
Rollout guide: https://www.sanity.io/docs/workflows/prerelease

Exports from @sanity/workflow-engine for scripts that load a config and act on its deployments. The CLI uses the same functions.

• deploymentResourceClients({client, deployment})(): ResourceClientResolver | undefined

  Builds a resourceClients resolver that serves every resource deployment.resourceAliases binds, so references to them pass the write-surface check and reads route to them. Each client is derived from client with withConfig, keeping its token, API host, and request-tag prefix; those credentials must reach every bound resource. Returns undefined when the deployment binds nothing beyond workflowResource. Throws ContractViolationError when a foreign resource is bound and client has no withConfig. A runtime-supplied reference to an unbound resource is still rejected with RefResourceUndeclaredError. See Read routing and the write surface.

• resourceAliasesToMap(resourceAliases)(): ResourceAliases

  Collapses a deployment's resourceAliases array into the alias-to-resource map that deploy expands @<name>: references against.

• expandResourceAliases(definition, resourceAliases)(): WorkflowDefinition

  Returns the definition with every @<alias>: reference expanded to the bound physical GDR. Fails, naming the definition and alias, when an alias is unbound or a standalone reference is malformed (for example @content:a:b or an empty id). A no-op when the definition references no aliases.

• refsOf(definition)(): LogicalRef[]

  The definition's outgoing spawn references, each {name: string, version?: number | 'latest'}. Deploy ordering and the delete referrer check use the same walk.

• validateDefinitionInputs(definitions)(): ValidateDefinitionInputsResult

  Checks definitions in authoring or stored shape for structure, cross-field rules, and GROQ syntax without a client. Returns {valid, results} with one result per definition. Deploy also checks duplicate names, spawn dependencies, resource bindings, project roles, and the reader-model acknowledgement, so a valid result does not guarantee a deploy succeeds. sanity-workflows definitions validate and the MCP workflows_validate_definition tool return the same report.

• deployedPartitionsGroq()(): string

  A GROQ query listing the distinct partitions that hold a deployed definition in the resource, sorted ascending. Run it with a client scoped to the workflow resource. It reports what is deployed, so a partition with nothing deployed is absent. It reads the stored tag field.

• definitionPartitionsGroq()(): string

  The same query narrowed to one definition; pass {definition} as the query parameters. A definition deployed under several partitions returns several results, and the caller must choose one.

• DEFAULT_PARTITION(): 'default'

  The partition a deployment resolves to when it omits partition.

defineWorkflowConfig throws defineWorkflowConfig failed validation (N issues): followed by one line per issue, each prefixed with the path of the failing key. The CLI prints the same text after Invalid config in sanity.workflow.ts:. An invalid partition value throws ContractViolationError with its message directly. Each line below is the issue text for one problem, for a deployment named dev, exactly as 0.37 prints it.

# No deployments
deployments: a config needs at least one deployment

# Invalid name
deployments[0].name: invalid name — ASCII lowercase + digits + dashes, no leading dash, no dots

# Invalid partition (thrown as ContractViolationError)
partition: invalid partition "Prod" — must match ^[a-z0-9][a-z0-9-]*$ (ASCII lowercase + digits + dashes, no leading dash, no dots)

# Duplicate name
deployments: duplicate deployment name "dev" — each deployment must use a unique name

# Shared resource, omitted partition
deployments: deployment "dev" shares its workflow resource with another deployment; set an explicit partition (use "default" to keep an omitted partition's address)

# Same resource and partition
deployments: deployments "dev" and "prod" share workflow resource + partition "x" — both would write into the same partition; change one deployment’s partition or resource

# Dataset id without a dot
deployments[0].workflowResource.id: invalid dataset resource id — expected "<projectId>.<dataset>"

# Unknown resource type
deployments[0].workflowResource.type: Invalid type: Expected ("dataset" | "canvas" | "media-library" | "dashboard") but received "bucket"

# Empty definitions
deployments[0].definitions: a deployment needs at least one definition

# Not a definition
deployments[0].definitions[0]: expected a workflow definition (an object with a string `name`)

# Invalid alias name
deployments[0].resourceAliases[0].name: invalid resource handle name — lowercase letters, digits and dashes only, no leading dash

# Duplicate alias name
deployments[0].resourceAliases: duplicate resource handle name "c" — each binding name must be unique within a deployment

# tag and partition differ
deployments[0]: Deployment "dev": "tag" and "partition" disagree. Remove the deprecated "tag" and keep the partition that addresses your stored workflows.

# tag not a valid partition
deployments[0]: Deployment "dev": "tag" is not a valid partition (ASCII lowercase + digits + dashes, no leading dash, no dots). Rename it to "partition" with the value that addresses your stored workflows.

# tag not a string
deployments[0]: Deployment "dev": "tag" must be a string. Rename it to "partition" and keep the existing value to retain access to stored workflows.

# Unknown runtime kind
deployments[0].runtime.kind: Invalid option: expected one of "function"|"durableFunction"|"selfHosted"

# Budget on a deployment runtime block
deployments[0].runtime.timeout: Invalid key: Expected never but received "timeout"

# Invalid telemetry logger
telemetry: expected a telemetry logger (an object with a `log` function)