Skip to content

4.0: one URL convention: named URL schemas, one suffix, one bound, checked by the build #8900

Open

Description

@KonstantinMirin

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_url appears 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 with maxLength: 2048 (governance/accepted-governance-agents.json), and 1 uses a private type.
  • trust/v1/trust.json defines its own #/definitions/https_url and uses it at 5 sites.
  • None of the 12 webhook target URLs requires HTTPS, for example core/push-notification-config.json#/properties/url. Yet docs/building/by-layer/L1/security.mdx says fetchers reject non-HTTPS URLs.
  • core/reporting-revision.json#/properties/schema_uri and core/creative-item.json#/oneOf/0/properties/content_uri are URLs named _uri. core/overlay.json#/properties/visual/properties/light and governance/check-governance-request.json#/properties/caller are 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

  1. Three named URL schemas. These are core/url.json (an absolute URL), core/https-url.json (the same, plus ^https://) and the existing core/macro-bearing-url.json. Every URL-valued property references one of them. Inline format: uri, inline ^https patterns and trust.json's private https_url go away. My open PR schemas: give every repeated constraint one definition, and fail CI on any repeat (#8525) #8536 names core/https-url.json for the sites that repeat ^https://; this proposal extends it to every URL.

  2. One bound. All three declare maxLength: 2048. security.mdx already prices a format: uri string at 2,048 characters, so the schema would state what the docs assume.

  3. 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), is core/url.json. security.mdx already applies this rule at fetch time, so for the 31 agent_url sites 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.

  4. One suffix. A URL-valued property is named url, *_url or *_urls, whatever the scheme. The _uri, endpoint, link and href spellings go. This holds for every AdCP-defined property, even when an external spec uses a similar name, so jwks_uri becomes jwks_url and authorization_endpoint becomes authorization_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.json in schemas: give every repeated constraint one definition, and fail CI on any repeat (#8525) #8536), and its property keeps a domain name such as credential_origins.

  5. The build enforces it. A scripts/lint-url-refs.cjs in the style of lint-language-tag-refs.cjs fails when:

    • a URL-named property doesn't resolve to one of the three schemas;
    • a URI format or an ^https pattern 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, link or href;
    • 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 $schema keyword 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

  1. KonstantinMirin commented on Nov 10, 2026

    @KonstantinMirin
    CollaboratorAuthor

    Supporting measurement for the "one bound" half of this, taken independently over bundle 3.2
    (1,054 portable documents, excluding bundled/ and mcp/).

    Your table reads "String-valued ones with a maxLength: 2 of 263". Counting from the other
    direction — nodes that state format: uri and have no maxLength at the node, at the array
    that holds it, or anywhere above it:

    296 nodes in 157 documents.

    Heaviest, one example pointer each:

    nodes document example pointer
    16 brand.json #/definitions/logo/properties/url
    16 protocol/get-adcp-capabilities-response.json #/properties/account/properties/authorization_endpoint
    10 core/registry-event.json #/oneOf/10/properties/payload/properties/agent_url
    9 core/attestation-capabilities.json #/properties/accepted_claim_types/items
    7 content-standards/artifact.json #/properties/url
    5 core/app-item.json #/properties/icon_url

    format: uri is RFC 3986 and RFC 3986 states no length, so each of those nodes admits a URL of
    unbounded length. Verified at 4,096 characters against the documents with
    Draft7Validator.FORMAT_CHECKER and rfc3987 installed — the documents accept it. Every real
    HTTP 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 263 row names; the 296/157 figure is the node-level
    count 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 and
    admits the bare string "https://" at 47 nodes in 31 documents — commented on #8398, since that
    issue proposes ^https:// as the whole constraint. If the named-URL-schema direction here is
    adopted, both findings are closed by it, which is an argument for doing this in one place rather
    than per site.

  2. added this to the 4.0 milestone on Nov 11, 2026
  3. added
    schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    on Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasschemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygienespec / protocol

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions