How to Validate an agent-policy.json File
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
Validating an agent-policy.json file means checking it against the AGENT-POLICY v0.1 conformance rules: valid JSON, all required fields present with values inside their domains, no action in both lists of one rule, no duplicate agent identifiers, a proper site URL, and a parseable review date. AgentGate's validator does it free, in seconds, for a single policy — and reports errors, which invalidate the document, separately from warnings, which do not.
What does "valid" mean here?
Exactly one thing: schema conformance. A valid verdict certifies that the document is built according to the format — fields, types, domains, and the structural rules. It does not certify that the terms are wise, sufficient, lawful, or obeyed, and the spec insists on the distinction: a validator finding of valid is not a legal opinion. This narrowness is a feature. Conformance is mechanically decidable, so two validators, given the same file, reach the same verdict — which is what makes "did you validate it?" a yes-or-no question across the whole ecosystem, and what the conformance page documents for this implementation.
What the validator actually checks
The checks follow the five conformance rules. Structure first: the document must be JSON and a top-level object. Fields next: the seven required top-level fields and the five required rule fields, each with the right type and a value from its domain — default_policy among allow, block, conditional; allowed among yes, no, conditional; commercial_terms among free, paid-tier, contact. Then the two relational rules humans keep breaking: no overlapping actions inside a rule, and no identifier used twice. Finally the formats: site an absolute URL, last_updated a parseable date, and signature present with null accepted. Unknown agent identifiers and unknown action names surface as warnings — noted, never fatal.
Validate twice: the draft and the live file
The draft check catches authoring errors while they are still cheap — the overlap pasted in from another rule, the identifier duplicated by a merge. The live check catches publishing errors, which are a different species: the wrong file deployed, the well-known path intercepted by middleware, the cache serving last month's version. Fetch the published URL, validate the body that returns, and compare its last_updated against your records. Owners who skip the second check occasionally discover, via an operator's confused email, that the world has been reading a policy they replaced weeks ago. The publishing guide builds this fetch into the release routine.
Reading a validator report like an owner
Errors are a stop sign: fix every one before the file represents you. Warnings are a reading exercise: each one names something the format tolerates but wants you to notice — an identifier outside the registry, an action outside the suggested vocabulary. Sometimes the warning is the ecosystem growing (a new agent, a new verb) and the right response is to keep it and move on; sometimes it is a typo wearing a warning's clothes — anthropic/claude for anthropic/claude-agent — and the right response is gratitude. The discipline is to have decided about every warning, which is why warnings vs errors gets its own guide. For fleets, the same checks run at scale through batch validation — up to 100 policies per call on Pro.
Make the validator a habit with an address in your workflow, not a website you remember under pressure. The pattern that survives contact with real teams is boring: the validator link sits in the same runbook as the deployment checklist, the review calendar names it, and the change log records its verdict alongside each edit — "validated, 0 errors, 1 warning owned" is a complete entry. Organisations that run policies as fleets industrialise the same habit through the batch API; individuals keep it with a bookmark and a rule that no policy edit is finished until its report exists. The tool is free either way. What you are actually maintaining is not the file — it is the reflex that the file is never trusted unverified.
Worked example: a marketplace's pre-launch validation finds three errors
Fictional example. Bidwell Auctions, a fictional estate-auction marketplace, validated its first policy the night before announcing agent access. The report came back with 3 errors and 2 warnings. The errors: checkout sat in both lists of its shopping rule (a copy-paste slip), one identifier appeared twice after two colleagues edited in parallel, and last_updated read "next Tuesday" — a placeholder a human understood and a parser did not. The warnings flagged a custom action, bid, which the marketplace kept deliberately: no suggested verb covers placing an auction bid. Fixes took 25 minutes. The launch announcement went out the next morning with a file that had earned its valid verdict — and bid still in it, warned and welcome.
The validation checklist
- Validate the draft. Run every new or edited policy through the validator before it ships.
- Fix all errors. Missing fields, domain violations, overlapping actions, duplicate identifiers, bad dates — all of them, not most of them.
- Decide on every warning. Keep the deliberate ones (new agents, new verbs); fix the accidental ones (typos).
- Validate the live copy. Fetch the well-known URL and validate what the server returns.
- Re-validate on change. Every edit, however small, gets a fresh run — small edits are where duplicates and overlaps breed.
Keep reading
The Five Conformance Rules of AGENT-POLICY v0.1 · Agent Policy Mistakes That Make a Policy Invalid · Agent Policy vs robots.txt, Compared · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
Is the validator free?
Yes — the single-policy validator is free and unlimited, like the generator. Paid tiers add scale and hosting, not basic checking: the batch API validates up to 100 policies per call on Pro. Nobody needs a paid plan to know whether one file conforms.
What is the difference between an error and a warning?
An error means the document breaks a conformance rule and is invalid — a missing required field, an action in both lists, a duplicate identifier. A warning means the document conforms but contains something outside the known lists — an unregistered identifier or an unsuggested action — which the format tolerates so it can grow.
Does valid mean my policy is legally sound?
No. Valid means the document conforms to the AGENT-POLICY v0.1 schema. The spec is explicit that a validator's verdict is not a legal opinion, and conformance checks say nothing about whether agents comply or whether your terms achieve your legal goals. It certifies the file's construction, nothing more.
Can I validate a policy that is not mine?
Yes. Paste any policy document into the validator — your own draft, a sample, a partner's published file fetched from their well-known URL. The validator makes no network requests itself; you bring the document to it. Checking a counterparty's file before relying on its terms is good practice.
My file validates but agents behave as if it says something else. Why?
Most often, they are reading a different copy: a cached older version, or a live file that is not the draft you validated. Fetch the well-known URL yourself and validate what returns. If the live file matches your intent, the disagreement is about interpretation or compliance — see the guide on agents ignoring a policy.
Generate a policy — free · Validate a policy · What an agent access policy is