Repository navigation
Description
Problem
Each URL-valued property is typed inline at its own site, so one concept validates differently from place to place. I measured static/schemas/source on main (811443077e):
| Measure | Sites |
|---|---|
Properties whose name says URL (*_url, *_uri, endpoint, link) |
266, with 72 names |
… typed through a named schema (core/macro-bearing-url.json) |
15 |
… typed inline with format: uri |
242 |
String-valued ones with a maxLength |
2 of 263 |
String-valued ones that require https:// |
60 of 263 |
URL-valued properties spelled _uri, endpoint or link |
22 |
| URI-typed properties whose name doesn't say URL | 74, with 50 names |
Some examples:
agent_urlappears at 45 sites with 5 typings. 31 sites accept any scheme (aao/agent-publishers.json#/properties/agent_url), 7 require^https://(core/creative-policy.json#/properties/accepted_verifiers/items/properties/agent_url), 5 use a host-validating regex, 1 uses a no-query regex withmaxLength: 2048(governance/accepted-governance-agents.json), and 1 uses a private type.trust/v1/trust.jsondefines its own#/definitions/https_urland uses it at 5 sites.- None of the 12 webhook target URLs requires HTTPS, for example
core/push-notification-config.json#/properties/url. Yetdocs/building/by-layer/L1/security.mdxsays fetchers reject non-HTTPS URLs. core/reporting-revision.json#/properties/schema_uriandcore/creative-item.json#/oneOf/0/properties/content_uriare URLs named_uri.core/overlay.json#/properties/visual/properties/lightandgovernance/check-governance-request.json#/properties/callerare URLs whose names don't say URL.
#8792 (for #8398) fixes the 3.3 part: it loosens 17 over-specified patterns to ^https://, so URL-named properties use 2 HTTPS patterns instead of 4. The rest of the table stays the same.
Every site is listed in this gist, with the script that produced the list and a draft of the check.
Proposal for 4.0
-
Three named URL schemas. These are
core/url.json(an absolute URL),core/https-url.json(the same, plus^https://) and the existingcore/macro-bearing-url.json. Every URL-valued property references one of them. Inlineformat: uri, inline^httpspatterns andtrust.json's privatehttps_urlgo away. My open PR schemas: give every repeated constraint one definition, and fail CI on any repeat (#8525) #8536 namescore/https-url.jsonfor the sites that repeat^https://; this proposal extends it to every URL. -
One bound. All three declare
maxLength: 2048.security.mdxalready prices aformat: uristring at 2,048 characters, so the schema would state what the docs assume. -
One rule for HTTPS. A URL that the receiving party fetches or calls is
core/https-url.json: agent URLs, webhook targets, JWKS and documents to download. A URL that only identifies something, or that a person opens (a landing page or a support page), iscore/url.json.security.mdxalready applies this rule at fetch time, so for the 31agent_urlsites and 12 webhook targets that accept any scheme today, the schema catches up with the docs. Every other fetch rule stays in prose, as URL validation is over-specified: eight patterns where ^https:// is enough #8398 and fix(schema): loosen over-specified URL patterns to ^https:// (#8398) #8792 settled. -
One suffix. A URL-valued property is named
url,*_urlor*_urls, whatever the scheme. The_uri,endpoint,linkandhrefspellings go. This holds for every AdCP-defined property, even when an external spec uses a similar name, sojwks_uribecomesjwks_urlandauthorization_endpointbecomesauthorization_url. A URL with a narrower meaning, such as an origin, gets its own named schema built on one of the three (core/https-origin.jsonin schemas: give every repeated constraint one definition, and fail CI on any repeat (#8525) #8536), and its property keeps a domain name such ascredential_origins. -
The build enforces it. A
scripts/lint-url-refs.cjsin the style oflint-language-tag-refs.cjsfails when:- a URL-named property doesn't resolve to one of the three schemas;
- a URI
formator an^httpspattern appears outside them (a named concept schema that references one of them may add a narrower pattern); - a URL-valued property is spelled
_uri,endpoint,linkorhref; - a property typed directly as a URL has no URL name.
Exceptions go in a dispositions file, with a reason each. They're only for a payload or keyword that another spec defines and AdCP carries: a JWT claim set's
sub, the JSON Schema$schemakeyword and the A2UI catalog. With one documented host allowlist, that's 7 entries. On main the draft reports 650 findings over 341 sites. The 643 that aren't exceptions go in a baseline that only shrinks and is empty at 4.0.0.
Why 4.0
Adding ^https:// or maxLength narrows what a receiver accepts, and a rename breaks everyone who uses the old name. A 3.x minor can add the new names and deprecate the old ones, and senders may emit both. Removing the old names and narrowing the types waits for 4.0. This fits #8756's T2 (one definition per concept). It builds on #8536 and #8792.
Related: the check accepts a *_url name or a named concept schema, so it doesn't constrain #5824's rename of format_id.agent_url. #8862 (how authorized_agents[].url matches) stays in prose. URIs used only as identifiers, such as claim types, get named schemas as the ID-types issue (#8899) proposes.
I'm happy to take this on.
Activity
KonstantinMirin commentedon Nov 10, 2026
Supporting measurement for the "one bound" half of this, taken independently over bundle 3.2
(1,054 portable documents, excluding
bundled/andmcp/).Your table reads "String-valued ones with a
maxLength: 2 of 263". Counting from the otherdirection — nodes that state
format: uriand have nomaxLengthat the node, at the arraythat holds it, or anywhere above it:
296 nodes in 157 documents.
Heaviest, one example pointer each:
brand.json#/definitions/logo/properties/urlprotocol/get-adcp-capabilities-response.json#/properties/account/properties/authorization_endpointcore/registry-event.json#/oneOf/10/properties/payload/properties/agent_urlcore/attestation-capabilities.json#/properties/accepted_claim_types/itemscontent-standards/artifact.json#/properties/urlcore/app-item.json#/properties/icon_urlformat: uriis RFC 3986 and RFC 3986 states no length, so each of those nodes admits a URL ofunbounded length. Verified at 4,096 characters against the documents with
Draft7Validator.FORMAT_CHECKERandrfc3987installed — the documents accept it. Every realHTTP implementation bounds it somewhere and the protocol does not say where, so each
implementation picks its own limit and they disagree.
This is the same defect your
maxLength: 2 of 263row names; the 296/157 figure is the node-levelcount including array items and nested positions, which is the population a generated type layer
has to reproduce.
One note on scope: we also measured that
pattern: "^https://"alone does not bound anything andadmits the bare string
"https://"at 47 nodes in 31 documents — commented on #8398, since thatissue proposes
^https://as the whole constraint. If the named-URL-schema direction here isadopted, both findings are closed by it, which is an argument for doing this in one place rather
than per site.