Skip to content

4.0: one named schema per ID concept, checked by the build #8899

Open

Description

@KonstantinMirin

Problem

Most AdCP IDs have no single definition. I measured every property named id, ids, *_id or *_ids, on main and on the #8536 head:

main #8536 head
ID sites 1,120 on 277 names 1,120 on 277 names
Plain type: string, nothing else 500 500
Constraints stated inline 457 70
Distinct inline patterns 17 4
Names whose sites accept different values 71, over 735 sites 69, over 719 sites
ID concepts with a named schema, of 184 in my draft registry 8 82

#8536 names about 90 ID schemas and moves the inline copies to them. It leaves the plain strings to a follow-up, on purpose, and that's where most of the disagreement now sits. On the #8536 head:

  • core/media-buy-id.json takes 1 to 255 characters, and 15 sites reference it. core/media-buy.json#/properties/media_buy_id, on the record itself, is a plain string, and so are 22 other media_buy_id sites.
  • brand_id names an advertiser brand at 7 sites and a rights-holder brand at 7, by their x-entity. Only the advertiser brand has a schema (core/brand-id.json, pattern ^[a-z0-9_]+$), and 3 of its 7 sites don't reference it, so they accept values it rejects.
  • signal_id is an object at 9 sites (core/signal-id.json) and a string at 4 (core/signal-local-id.json). format_id and format_ids mix the two JSON types the same way.
  • The 82 ID schemas use 14 different patterns. 22 write the length as a quantifier, such as ^[A-Za-z0-9_.:-]{1,255}$, and 41 have no maxLength.

None of this was a decision. Nothing compares a new ID field with the other fields that carry the same ID.

Every site is listed in this gist, with the concept I'd assign it, the script that produced the list, a draft concept registry and a draft of the check.

Proposal for 4.0

  1. One schema per concept. Each kind of record has one titled schema under core/, carrying its x-entity, and every site references it. A concept isn't a property name: list_id is a property list or a collection list, and request_id an account request or a match request. 18 names cover more than one concept, and each site references the schema of the one it means.

  2. A few ID classes. Each concept schema follows one class. The first three come from build(schemas): inventory value concepts and flag structural twins #8504:

    • opaque: a string of 1 to 255 characters;
    • token: opaque, plus ^[A-Za-z0-9_.:-]+$;
    • slug: opaque, plus ^[a-z0-9_]+$;
    • standard: the syntax a published standard or issuer defines, such as a UUID or a sellers.json seller ID.

    The bound is 255 unless something published says otherwise. 27 concepts keep another bound with its source, such as 64 for subscriber_id. The bound is maxLength, never a quantifier in the pattern.

  3. A registry instead of per-site annotations. One file lists each concept with its schema and class, and the property names whose stem doesn't say the concept. It replaces scripts/x-entity-field-map.json. A site states only its $ref and description: no inline pattern or length, and no x-entity of its own, which 308 sites state today.

  4. An ID is a string. A structured reference is a _ref property, like signal_ref. Most object-valued format_id and signal_id sites are deprecated already. The 13 sites whose _id name holds a boolean, a number or a map belong to the field-naming issue (4.0: one naming convention for properties (casing, type suffixes, one name per concept), checked by the build #8902).

  5. The build enforces it. A check fails when:

    • an ID site doesn't reference its concept's schema, or states a constraint of its own;
    • an ID value isn't a string;
    • a property name maps to no registered concept;
    • a concept schema is missing, doesn't match its class, or carries a different x-entity.

    Its shrink-only baseline has 890 entries on the schemas: give every repeated constraint one definition, and fail CI on any repeat (#8525) #8536 head, and none at 4.0.0. The check itself changes nothing on the wire, so it can land before 4.0 and hold new IDs to the rule right away.

Why 4.0

Pointing a plain string at its concept schema tightens it. On the #8536 head, 727 string ID sites have no length bound, and they'd gain one. A minor only adds, so that waits for the major.

This is the ID follow-up that #8536 defers, and the ID-class step #8504 plans. It fits #8756's T2: one definition per concept. Related: #7850 (account_id as the only account reference) and #7443 (portable domains in brand references).

I'm happy to take this on.

Activity

  1. added this to the 4.0 milestone on Nov 11, 2026
  2. 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