Validation

xema/validate-deliverables asks do these artifacts satisfy the spec, and answers with a verdict the workflow branches on rather than an exception. You give it artifact ids; it resolves the spec server-side and returns a judgement.

A second check is described below for completeness and no longer exists: harvest-time discovery, inside the producing job, which asked which file in the workspace is the deliverable. The harvester was deleted on 2026-08-29, so no workspace file becomes an artifact. See the note on the section index.

Two checks, two jobs

Neither of them ends the run on its own. Validation is a fact the workflow reads; what a failing verdict means is a decision the workflow author writes as an if: gate.

Harvest-time discovery (not running)

This section describes the harvester's intended behaviour. Nothing constructs it today, so none of it happens: no workspace file becomes an artifact, and a producing job emits only its structured handoff.

Discovery is schema-driven, not name-driven. The harvester walks the canonicalPath and any fallbackPaths declared by the spec's output contract, parses each candidate as JSON, and asks deliverable-specs-api — POST /deliverable-specs/{ref}/validate-content — which one matches the spec's content shape. The first match wins; when several match, the canonical path is preferred. The agent can write any reasonable filename and discovery still works.

Two kinds do not take this path, because their deliverable is not a single JSON value: MARKDOWN_DOCUMENT and ENDPOINT_FETCH. For those the endpoint answers applicable: false and the harvester uses its own kind-specific walk.

When nothing matches, the harvester records a warning naming every path it tried and why each candidate was rejected, and returns no structured value. It does not throw — the producing job completes, and the downstream gate is what reacts.

xema/validate-deliverables

1validate:
2  needs: [draft]
3  uses: xema/validate-[email protected]
4  with:
5    deliverableSpecRef: architecture-standard
6    strictness: standard
7    artifactIds:
8      - ${{ needs.draft.outputs.structuredOutput.artifactId }}
9  outputs:
10    verdict: ${{ job.outputs.verdict }}
11    issues: ${{ job.outputs.issues }}

artifactIds takes any artifact ids. The only artifact a workflow agent job emits today is its promoted structuredOutput handoff, so that is what there is to pass. Note that validating a JSON handoff against a spec written for a markdown document will not pass — the spec and the artifact have to be about the same thing.

Each issue is { severity, code, message, artifactId, path }, where severity is error or warning and artifactId / path may be null.

The action resolves the spec and computes the verdict server-side, so changing a spec's rules changes the verdict without redeploying a worker. It declares artifacts: read, a one-minute startToClose timeout, and up to two attempts — with ValidationError and UnauthorizedError marked non-retryable. Those retries are about the validation call failing; a fail verdict is a successful call and is never retried.

What it checks

Two cross-cutting artifact-count rules apply to every kind, and each kind may add rules of its own. Today exactly one built-in kind does.

code is a string on the wire, not a closed kernel enum — a biome that contributes its own deliverable kind contributes its own codes along with it. The three above are what the built-in kinds emit.

Deeper per-kind content checks — a full Zod evaluation, schema-match reporting against the produced artifact — are not part of this action today. What the spec's content shape does gate is harvest-time discovery, above.

Strictness only moves severity

strictness does not change which rules run or what they look at. It decides how an issue is graded:

strict is accepted and is evaluated identically to standard today.

The verdict follows from the issues

1any issue with severity 'error'  →  fail
2otherwise, any issue at all      →  warn
3no issues                        →  pass

So lenient turns what would have been a fail into a warn — the issues are identical, and only their grading moved. A workflow that wants to proceed on warnings writes verdict != 'fail'; one that wants a clean bill writes verdict == 'pass'.

Branching on the verdict

The point of returning a verdict rather than throwing is that the workflow author decides what happens next. The branch is an ordinary job with an if::

1publish-fail:
2  needs: [validate]
3  if: ${{ needs.validate.outputs.verdict != 'pass' }}
4  uses: xema/publish-[email protected]
5  with:
6    spaceSlug: architecture
7    slug: ${{ format('arch-issues-{0}', xema.run.id) }}
8    title: ${{ format('Validation {0}', needs.validate.outputs.verdict) }}
9    markdown: ${{ format('# Verdict: {0}\n\n```json\n{1}\n```\n', needs.validate.outputs.verdict, toJSON(needs.validate.outputs.issues)) }}

The same issues array is what an author renders, files, or forwards. Nothing else has to be reconstructed from the run history.

The mirror-image publish-pass job — publishing the produced deliverable itself on a passing verdict — is not expressible today, so no example of it is given here. xema/publish-kb's artifactId branch reads payload.body from the artifact version and refuses any other shape; the agent job's one artifact is a json_payload handoff, which has no body. Only the inline markdown form, above, reaches the knowledge base.

Retrying a failed deliverable

There is no retry inside the producing job. If a workflow should try again when a deliverable does not satisfy its spec, that is expressed with ordinary workflow structure: a second producing job, gated on verdict != 'pass', taking the issues array as part of its input.

Keeping it in the workflow keeps it visible: the second attempt is a job in the graph, with its own inputs, its own artifacts, and its own verdict.

Previous: ← Output Envelope Next: Examples →