wais-validator 0.1.0

Validate WAIS agents.json compliance. CLI + library.

wais-validator

Validate WAIS agents.json manifests against the spec. CLI tool + Python library.

Checks your manifest for schema compliance, scope validity, risk level rules, endpoint liveness, JWKS reachability, and cross-field consistency — then gives you a score with actionable fix suggestions.

Install

pip install -e ".[dev]"

Requires Python 3.10+ and wais-pod.

Usage

Validate a live site

wais validate https://example.com

Fetches /.well-known/agents.json automatically.

Validate a local file

wais validate --file agents.json

Schema-only mode (skip HTTP checks)

wais validate --file agents.json --schema-only

JSON output for CI

wais validate --file agents.json --format json

Exit code: 0 if score >= 50 (grade C or above), 1 otherwise.

What it checks

Category	What	Severity
Schema	JSON Schema validation against WAIS v0.1 spec	FAIL
Scopes	Standard scope validity, custom scope declarations, standard_scopes_used consistency	FAIL / WARN
Risk	Risk level overrides (can't lower below WAIS minimum), confirmation/payment vs risk	FAIL / WARN
Endpoints	HTTP liveness for each action endpoint (HEAD with OPTIONS fallback)	FAIL / WARN
Auth	JWKS reachability for each trusted issuer	FAIL / WARN
Consistency	HTTPS enforcement, duplicate action IDs, payment section presence	FAIL / WARN

Example output

A manifest with issues:

Validating: agents.json

  ✓ Schema Validation — 1 check(s) passed

  Risk Level Checks  2 error(s)
    ✗ Action 'cheap_checkout' sets risk_level to 'low' but the WAIS minimum for 'checkout.execute' is 'high'
      at actions[0].risk_level
      Fix: Set risk_level to "high" or higher (or remove it to use the standard).

  Consistency Checks  2 error(s), 1 warning(s)
    ✗ site.url uses 'http://' but WAIS requires HTTPS in production
      at site.url
      Fix: Change site.url to use https://. Only http://localhost is allowed for development.
    ✗ Duplicate action id 'browse_catalog' — also defined at actions[0]
      at actions[1].id
      Fix: Rename one of the 'browse_catalog' actions to have a unique id.
    ⚠ Some actions have requires_payment=true but the manifest has no 'payment' section
      at payment
      Fix: Add a "payment" section to your manifest with model, providers, and currencies.

╭──────────────────────── Result ────────────────────────╮
│ Score: 63/100    Grade: C    5 issue(s) found.         │
╰────────────────────────────────────────────────────────╯

A clean manifest:

Validating: agents.json

  ✓ Schema Validation — 1 check(s) passed
  ✓ Scope Checks — 4 check(s) passed
  ✓ Risk Level Checks — 4 check(s) passed
  ✓ Endpoint Liveness — 5 check(s) passed
  ✓ Authentication (JWKS) — 1 check(s) passed
  ✓ Consistency Checks — 1 check(s) passed

╭──────────────────────── Result ────────────────────────╮
│ Score: 100/100    Grade: A    No issues found.         │
╰────────────────────────────────────────────────────────╯

Scoring

Category	Weight
Schema	30 pts
Scopes	15 pts
Risk	15 pts
Endpoints	20 pts
Auth	10 pts
Consistency	10 pts

Each FAIL deducts proportionally from its category. Warnings deduct 25% of what a FAIL would. Skipped categories (e.g. --schema-only) redistribute their points.

Grade	Score
A	90–100
B	75–89
C	50–74
D	25–49
F	0–24

Use as a library

from wais_validator import SYNC_VALIDATORS, compute_score, Category
import json

manifest = json.load(open("agents.json"))

results = []
for validator in SYNC_VALIDATORS:
    results.extend(validator(manifest))

score, grade = compute_score(results, active_categories={
    Category.SCHEMA, Category.SCOPES, Category.RISK, Category.CONSISTENCY
})

for r in results:
    if r.fix:
        print(f"{r.severity.value}: {r.message}\n  Fix: {r.fix}")

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v

License

MIT