agent-permissions.json validator

What is agent-permissions.json?

agent-permissions.json is a permission manifest for web agents, defined by the Lightweight Agent Standards Working Group at v1.0.0. It declares what an agent may do on your pages, not merely what it may fetch: resource_rules bind a verb (one of 16, such as click_element or submit_form) and a CSS selector to an allow or deny, while action_guidelines carry RFC 2119 directives for higher-level behaviour. It lives at /.well-known/agent-permissions.json or wherever a <link rel="agent-permissions"> tag points.

Why should I publish an agent-permissions.json file?

robots.txt tells crawlers which URLs are off-limits, but says nothing about actions. agent-permissions.json is the complement: it declares which agents may read, write, or delete, and under what conditions. Adopting early is a bet that the spec ratifies - if it does, early adopters set the norms. If it doesn’t, the cost was writing a small JSON file. Don’t have one yet? Build a schema-valid file in the agent-permissions.json generator and come back here to verify it against your live site.

What does the agent-permissions validator check?

• C7 — Schema. Full validation against the published v1.0.0 JSON Schema: the required metadata (with a semver schema_version and ISO-8601 last_updated) and strict; the closed 16-verb enum; the RFC 2119 directive enum; and the schema’s refusal of unknown properties.
• Invalid selectors. A selector that is not parseable CSS cannot be applied by any agent, so the rule silently does nothing.
• Contradictory rules. The same verb and selector both permitted and forbidden. Equal specificity means the outcome is implementation-defined.
• No-op policies. strict is false and no rules or guidelines are declared — the file grants exactly what publishing nothing would.
• Dead selectors. Reported when a rule’s selector matches no element on the page. You believe .private-area is protected; there is no such element.
• Dangling api[] references. Your manifest points agents at an MCP, OpenAPI, or A2A endpoint as a safer alternative to the UI — and we check the site actually publishes it. A broken escape hatch sends the agent right back to the interface you were steering it away from.

The last three require having scanned the whole site, not just the file. A validator that only reads your JSON cannot tell you that a selector matches nothing, or that the API you advertise is not there.

Illustrative example

{
  "metadata": {
    "schema_version": "1.0.0",
    "last_updated": "2026-07-14T00:00:00Z",
    "author": "Example Corp"
  },
  "strict": false,
  "resource_rules": [
    { "verb": "read_content", "selector": "*", "allowed": true },
    { "verb": "follow_link", "selector": ".private-area", "allowed": false },
    {
      "verb": "click_element",
      "selector": "#buy",
      "allowed": true,
      "modifiers": { "burst": 5, "human_in_the_loop": true }
    }
  ],
  "action_guidelines": [
    {
      "directive": "MUST NOT",
      "description": "Send unsolicited direct messages to end users.",
      "exceptions": "MAY message site administrators."
    }
  ]
}

This is the real v1.0.0 shape. metadata and strict are required; resource_rules, action_guidelines and api are optional. The schema forbids unknown properties, so an invented field is a validation error, not a harmless extra.

An invalid file is worse than no file

The spec is explicit about what happens when a manifest fails validation: a consumer “SHOULD treat the file as absent and MUST NOT grant additional permissions based on it”. So a malformed policy does not fail open or closed — it does nothing at all, while the publisher believes a policy is in force. That is why we validate against the full v1.0.0 schema rather than waving through anything that parses: a broken policy should be reported as broken.