Repository navigation
Description
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.jsontakes 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 othermedia_buy_idsites.brand_idnames an advertiser brand at 7 sites and a rights-holder brand at 7, by theirx-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_idis an object at 9 sites (core/signal-id.json) and a string at 4 (core/signal-local-id.json).format_idandformat_idsmix 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 nomaxLength.
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
-
One schema per concept. Each kind of record has one titled schema under
core/, carrying itsx-entity, and every site references it. A concept isn't a property name:list_idis a property list or a collection list, andrequest_idan account request or a match request. 18 names cover more than one concept, and each site references the schema of the one it means. -
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 ismaxLength, never a quantifier in the pattern. -
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$refand description: no inlinepatternor length, and nox-entityof its own, which 308 sites state today. -
An ID is a string. A structured reference is a
_refproperty, likesignal_ref. Most object-valuedformat_idandsignal_idsites are deprecated already. The 13 sites whose_idname 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). -
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