Reference validator for Agentic Workflow Protocol (AWP)
manifests: the YAML restrictions, the JSON Schema and the semantic rules of AWP v1alpha1,
v1alpha2 and the proposed v1alpha3 (each document is checked against the schema of its own
apiVersion), per
conformance profile, with digest verification and machine-readable diagnostics.
- Web: validator.agenticworkflowprotocol.org – runs in the browser, the manifest is not uploaded.
- CLI:
awp validate, with the output formats and exit codes of the AWP CLI output formats. - Editor and viewer: editor.agenticworkflowprotocol.org (awp-editor) is built on this validator.
- Library: for Node.js and for the browser (one ES module, no
eval), to validate manifests inside your own runtime, editor or CI.
Status: alpha, like the specification. The validator passes the AWP conformance suite (validator role, spec 11.1); it is not a runtime and says nothing about runtime conformance.
npm install --save-exact @agenticworkflowprotocol/validatorEvery push to main with a new version in package.json is released automatically: tag, GitHub release and npm with provenance (.github/workflows/publish.yml). Without registry access, install the
tarball of a GitHub release:
npm install --save-exact \
https://github.com/agenticworkflowprotocol/awp-validator/releases/download/v0.1.0/agenticworkflowprotocol-validator-0.1.0.tgzEach release also contains the browser bundle awp-validator.mjs, the JSON Schema and
SHA256SUMS. Node.js 20 or newer. Runtime dependencies: ajv and yaml (pinned).
npx awp validate workflow.yaml
npx awp validate --profiles core,mcp --verify-digest workflow.yaml other.yaml
cat workflow.yaml | npx awp validate --output json -workflow.yaml:31:11: error dependsOn.unknown-step /spec/workflow/1/dependsOn/0: dependsOn names non-existent step "ghost"
workflow.yaml (Workflow vulnerability-fixer 0.1.0): invalid, 1 error
| Option | Meaning |
|---|---|
--profiles <list> |
Supported profiles (core, governance, audit, security, mcp, a2a). Fields of other profiles are rejected (spec 3.3). Default: all. |
--verify-digest |
Verify metadata.integrity.digest (spec 9.1). |
--strict |
Warnings fail the command. |
--output text|json |
json prints the envelope { awp, command, ok, result }. |
--quiet |
Only diagnostics of severity error. |
Exit codes: 0 valid, 1 invalid, 2 usage error, 3 file could not be read.
import { validateText, validateManifest } from '@agenticworkflowprotocol/validator';
// Text (YAML or JSON, several documents allowed), with line and column per diagnostic.
const { documents } = validateText(text, { file: 'workflow.yaml', profiles: ['core', 'mcp'] });
if (!documents.every((d) => d.valid)) {
for (const d of documents.flatMap((doc) => doc.diagnostics)) {
console.error(`${d.source.line}:${d.source.column} ${d.code} ${d.path}: ${d.message}`);
}
}
// An already parsed value, for example a request body.
const result = validateManifest(manifest, { profiles: ['core', 'mcp'] });Diagnostics follow section 3 of the CLI output formats:
severity, code (stable), message, path (JSON Pointer), section, document, source.
Further exports: formatText, formatJson (the awp validate formats), manifestDigest, jcs,
migrateToV1alpha3, schemas (by API version), schema (current draft v1alpha2), provenance, KNOWN_PROFILES, API_VERSIONS. Each
document result carries awp, the API version it was validated as. Types are included
(types/index.d.ts). The schema files are also available as
@agenticworkflowprotocol/validator/schema/v1alpha1.json, .../schema/v1alpha2.json, .../schema/v1alpha3.json and
.../schema.json (current draft).
A runtime that supports only some profiles passes exactly those, so that manifests with fields of other profiles are rejected instead of being run without them:
const { valid, diagnostics } = validateManifest(manifest, { profiles: ['core', 'mcp'] });
if (!valid) throw new ManifestRejected(diagnostics.filter((d) => d.severity === 'error'));
// Runtime-specific rules (deployment policy) come after this check and may only be stricter.import { validateText } from '@agenticworkflowprotocol/validator/browser';The browser entry is a single bundled ES module (dist/browser/awp-validator.mjs, also attached
to every release). The JSON Schema validator is precompiled, so it runs under a
Content-Security-Policy without unsafe-eval, and digests use a synchronous SHA-2 implementation.
vendor/awp/ is an unchanged copy of the schemas of every supported API version, the semantic
rules, the conformance suite and the examples of the specification repository at the commit recorded in
PROVENANCE.json, with a SHA-256 hash per file. npm test fails if a vendored file differs.
Update to a newer specification commit:
node scripts/sync-spec.mjs ../agenticworkflowprotocol.org # clean checkout at the wanted commit
npm testnpm ci
npm test # builds dist/, then runs the conformance suite (Node.js and browser bundle) and unit tests
npm run build # dist/browser/ and dist/site/The website in site/ is built into dist/site/ and deployed by the Cloudflare Pages project
awp-validator on every push to main. The output directory is set in wrangler.toml; the build
command npm ci && npm run build is set in the Pages dashboard. site/_headers sets a strict
Content-Security-Policy (no inline scripts, no external requests).
- Set the new
versioninpackage.json(semantic versioning) and add a## [x.y.z]section toCHANGELOG.md. - Push to
main(directly or by merging a pull request).
The publish workflow runs on every push to main. If the version is not on npm yet, it runs the
tests, tags the commit vx.y.z, creates the GitHub release with the artefacts and publishes to npm
through trusted publishing. Pushes without a new version stop after the check.
Apache-2.0. The vendored specification files keep their licenses (vendor/awp/LICENSE,
LICENSE-SPEC). The browser bundle includes ajv (MIT), yaml (ISC) and @noble/hashes (MIT).
AWP provides machine-readable governance primitives that can help organizations implement and enforce their own compliance requirements. Compliance depends on the implementation, organizational controls and applicable regulatory requirements.