feat: spec-conformant way to authorize an agent for all listed properties (+ builder/validator support)

[bokelley]

Problem

Publishers in production routinely ship adagents.json files where authorized_agents[] entries carry only {url, authorized_for} — no authorization_type, no selector. Examples from the wild include wonderstruck.org and Raptive's published files. These files don't satisfy any branch of the schema's oneOf (every variant requires authorization_type + a matching selector), but the publisher's intent is unambiguous: "this agent is authorized for everything I list."

Today the AdCP ecosystem has three answers to that intent and none are good:

1. Strict per the schema (Python SDK's get_properties_by_agent): resolves to []. Products can't bind to the publisher even though the file looks "valid" to humans.
2. Permissive by accident (JS SDK, today): attributes all top-level properties[] to every listed agent regardless of authorization_type. Works operationally, drifts from the schema, indistinguishable from a buggy implementation.
3. Local shim (salesagent): we just added explicit permissive fallback (see salesagent#377). It works but every consumer will reimplement this differently — and the spec hasn't acknowledged what they're working around.

The root cause is that the spec has no first-class way to say "authorize agent X for everything I list" without enumerating it via property_ids / property_tags / inline properties. Publishers reach for the shortest expression of intent, which produces bare entries.

Proposed fix

Add a spec-conformant authorization variant whose meaning is "agent is authorized for every property in the file's top-level properties[] array." Two reasonable shapes:

Option A — new authorization_type value:

{
  "url": "https://wonderstruck.sales-agent.scope3.com",
  "authorized_for": "Display banners",
  "authorization_type": "all_top_level_properties"
}

Schema adds a 7th oneOf variant: {required: [url, authorized_for, authorization_type]} where authorization_type is constrained to the literal "all_top_level_properties". No selector field needed — the top-level properties[] is the implicit selector.

Option B — explicit all_properties: true selector:

{
  "url": "https://wonderstruck.sales-agent.scope3.com",
  "authorized_for": "Display banners",
  "authorization_type": "all_properties",
  "all_properties": true
}

Symmetric with the other variants (each variant has a selector field that names the binding). Arguably uglier but consistent.

I think A is cleaner — there's no useful payload beyond the discriminator itself, so a paired selector field is dead weight. Either way, the value of having this is that bare-entry behavior gets a name and a stable spec citation, so SDKs can stop divining intent.

Companion: builder UX

The AAO builder at agenticadvertising.org/publisher should default to producing typed entries. Concretely:

• When a publisher adds an agent to their adagents.json, the wizard should prompt: "Which properties is this agent authorized for? (a) All of them, (b) Specific IDs, (c) By tag, (d) Inline list."
• "(a) All of them" produces the new spec-conformant shape from this proposal.
• Bare-entry output should not be possible from the builder.

Companion: validator

Companion to adcp#4476 (validator currently reports schema-invalid files as valid: true). Once this proposal lands:

• Bare entries become a soft warning: "This entry uses the legacy bare shape. Spec-conformant equivalent: authorization_type: 'all_top_level_properties'. Still resolves the same way under permissive SDK modes — see adcp-client-python#711."
• Bare entries are no longer flagged as invalid (since the new variant gives them a clean migration target), but they're not silently passed either.

The combination is: publishers who want "authorize for everything" have a typed expression they can use, the validator nudges legacy files toward it, and SDKs can stop carrying permissive fallbacks indefinitely (we'd close adcp-client-python #711 once both SDKs support the new variant and the long tail of legacy files has migrated).

Cross-references

• adcp-client-python #711 — Python SDK permissive resolver (operational stopgap; would be deprecated once this lands)
• adcp-client #1721 — JS SDK per-agent resolution gap (related: needs both strict and permissive modes until new variant ships)
• adcp#4476 — strict validator behavior
• salesagent#377 — operator-facing UI model that surfaced the gap

Willing to PR

Happy to PR the schema change and a docs patch if the team agrees on the direction (and lands on A vs B).

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol, registry / discovery
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Option A is technically sound — discriminator-by-type-only is valid JSON Schema draft-07, new oneOf variant is non-breaking. One blocker if Option A ships: the spec must define normative behavior when properties[] is absent or empty (does all_top_level_properties resolve to zero entries or a wildcard?). Nit: all_properties is shorter and closer to the existing naming convention than all_top_level_properties.
• adtech-product-expert: The schema already documents a property_tags + synthetic "all" tag pattern that covers the same semantic (schema examples, lines 821–838; docs at adagents.mdx). The production failures are SDK bugs and a docs visibility gap, not a missing variant. Adding a new value creates two canonical ways to say "authorize everything," splitting consumer code paths. No schema change is needed to fix the Python SDK's silent-[] behavior or the JS SDK's permissive drift.

My take: Experts split on a genuine design question: new schema surface vs. better docs and SDK fixes. Both paths are non-breaking; the choice is about protocol ergonomics and future implementer burden.

@bokelley, your call — two paths:

Path 1 — new authorization_type variant (schema change, minor bump → 3.1):

{
  "url": "https://agent.example.com",
  "authorized_for": "Display banners",
  "authorization_type": "all_top_level_properties"
}

Publishers get a first-class typed expression. Spec PR must add normative language for the empty-properties[] edge case. SDKs adopt the new branch and deprecate permissive shims once both ship.

Path 2 — docs + SDK fix, no schema change:

{
  "url": "https://agent.example.com",
  "authorized_for": "Display banners",
  "authorization_type": "property_tags",
  "property_tags": ["all"]
}

Requires publishers to define an "all" tag covering all their properties. Validator soft-warning on bare entries points here. SDK fixes the silent-[] behavior independently. No new schema surface; avoids two "authorize everything" idioms.

(Builder UX change — prevent bare-entry output from the publisher wizard — is worth shipping regardless of which path wins.)

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01J93SeeM9U7BJ7qowiAL4aQ

---

Generated by Claude Code