The Utos workflow specification: the protobuf API and the documents that define what it means. Utos is a specification, not a platform — implementations conform to it, and the conformance corpus in this repository is how they show it.
| Package | Holds |
|---|---|
utos.workflow.v1 |
What a workflow is: Workflow, activities, WorkflowBundle, and the values a run carries (WorkflowValue, Blob) |
utos.daemon.v1 |
How workflows are run: DefinitionService, ExecutionService, ObservabilityService, BlobService |
There is no registry package. Workflows are published to OCI registries, which already define distribution and content addressing for what they store.
Behaviour that the .proto files cannot express on their own is specified in docs/. These are
normative — every implementation is expected to conform. Each document owns one subject, and the
others refer to it rather than restating it.
Authoring and building
| Document | Owns |
|---|---|
| Workflow source format | What authors write, and its mapping onto utos.workflow.v1.Workflow and a WorkflowBundle |
| Bundle validation rules | Every structural and referential rule a WorkflowBundle must satisfy |
| Canonical bundle digest | The byte form behind WorkflowReference.digest |
The language
| Document | Owns |
|---|---|
| Template expressions | The {{ }} and condition language — a JavaScript subset — the names in scope, the Node.js globals, and the guarantees every evaluator makes |
Data
| Document | Owns |
|---|---|
| Workflow values | What a run carries (WorkflowValue), and how tools convert it to and from JSON |
| Workflow schemas | What a workflow declares about its input, output, emissions and environment, and where each declaration is checked |
| Binary data | Blob and File: bytes inline or in object storage, HTTP bodies, getting bytes into and out of a run, retention, provenance, and BlobService |
Execution
| Document | Owns |
|---|---|
| Execution output streams | What emit, onEmitted and WatchOutput guarantee: ordering, durability, back-pressure |
A newcomer reads the source format first, then template expressions, then whichever of the rest their work touches.
Every rule has a stable code, UTOS- plus a family letter and three digits. The code is the
contract and the message text is not: fixtures assert codes, and implementations word messages
as they like. A retired code is never reused.
| Family | Checked | Defined in |
|---|---|---|
S### |
While a source document is read and built | source format |
B, D, M, A, T, C, V0## |
On a bundle, at load | bundle validation |
E0## |
On a bundle, at load — the expression grammar | template expressions |
H0## |
On a bundle, at load — its schemas | workflow schemas |
V1## |
On a run's input, at schedule | workflow values |
E1## |
While an expression is evaluated | template expressions |
H1## |
While a run crosses a declared boundary | workflow schemas |
F1## |
While a run handles binary data | binary data |
Load-time codes are reported as code + path. Codes raised while a run proceeds are reported as
a WorkflowError, and those raised at schedule as INVALID_ARGUMENT carrying
google.rpc.BadRequest.
conformance/ holds cross-implementation fixtures, one corpus per question:
| Corpus | Asks | Run by |
|---|---|---|
validation/ |
Does this bundle validate? | Every implementation of the bundle rules |
source/ |
What does this document map to? | Every front end that reads the source format |
evaluation/ |
What does this expression evaluate to? | Every expression evaluator |
schema/ |
Does this value satisfy this schema? | Every implementation that checks data against schemas |
The spec, utos/sdk-dotnet, utos/daemon-dapr and utos/cli share one version, and its minor
is the spec: 0.20.x anywhere means implements spec 0.20. A change to the spec is a new minor;
a correction that changes no behaviour is a patch, and an implementation need not release with it.
A release gives its version only to what it changed, so each repository's versions may skip
numbers. See CHANGELOG.md.
- utos/sdk-dotnet — the .NET SDK on nuget.org:
Utos.Workflow(the message types and the content digest),Utos.Workflow.Source(the source format),Utos.Workflow.Validation(the bundle rules),Utos.Daemon.ClientandUtos.Daemon.Server. It is released together with the spec. SDKs in other repositories subscribe to this repository'sv{version}tags; no Buf Schema Registry account is needed. - utos/daemon-dapr — the reference daemon.
- utos/cli — the
utoscommand.