Repository navigation
Description
Problem
A schema's identity is spread over its directory, file name, root title, index.json section, the manifest's protocol field and its published URL. Only one relation holds everywhere: the root $id equals /schemas/<path> in all 1,113 files, though no check asserts it (tests/schema-validation.test.cjs checks only the /schemas/ prefix). The rest drift. I measured main (18da1a4559):
| Relation | Today |
|---|---|
$id = /schemas/<path> |
1,113 of 1,113 |
Published only at /schemas/<version>/<path> |
39 async response schemas are published a second time under core/async-response-refs/ |
index.json section = directory |
72 entries sit elsewhere (governance in property/, collection/, content-standards/; brand-protocol in brand/) |
Task directory is a protocol in enums/adcp-protocol.json |
33 of 84 registered tasks aren't |
*-request/*-response file is a registered task message |
21 aren't |
Root title = file name |
888 of 1,113 |
| File name used once | 6 names repeat across directories |
Cross-file $ref targets a file |
135 point inside another file |
| One local-definitions keyword | definitions 48 times, $defs in 5 files |
| One path per schema | 8 groups define one schema at 19 paths |
Some examples:
list_creative_formatshas two different request schemas, inmedia-buy/andcreative/, andindex.jsonlists both. The build names tools after files and keeps the last one it reads, so the published manifest only has the media-buy one.build_creativeis listed undercreativeinindex.jsonand documented underdocs/creative/, but its files are inmedia-buy/, so the manifest saysprotocol: media-buy.core/tasks-get-request.jsonandcore/tasks-list-{request,response}.jsondefine the same schemas asprotocol/get-task-status-request.jsonandprotocol/list-tasks-{request,response}.json. Nothing references thecore/copies, but they're published, andcore/tasks-get-response.jsonhas already drifted from its twin.extensions/adcp.jsonreferenceshttps://adcontextprotocol.org/schemas/3.2.1/core/opportunity-context.json, the only source$refthat isn't/schemas/<path>. Source validation fails unlessdist/schemas/3.2.1/is present.
None of this was a decision. Each relation is kept by hand. Every site is listed in this gist, with the scan that produced the list and a draft of the check.
Proposal for 4.0
From 4.0.0, every new schema follows these rules. In 4.0.0, existing schemas get every fix that moves no file, and their moves follow in 4.x (items 7 and 8).
- The path is the identity. A schema lives at
<domain>/<name>.json, its$idis/schemas/<domain>/<name>.json, and it's published only at/schemas/<version>/<domain>/<name>.json. No second published copy, no versioned URL in source, no version directory (trust/v1/). - The domain is the owning protocol. A schema lives in the directory of the protocol that owns it, named as in
enums/adcp-protocol.json, or incorewhen protocols share it. Theindex.jsonsection, the manifest'sprotocoland the docs folder use the same name. Whichcorefiles belong to one protocol is for the layer issue (4.0: a declared layer order for the schemas, with no upward refs, no skip-layer refs and no cycles, checked by the build #8898). - A task's files are named after the task. One pair per task:
<protocol>/<task-name-kebab>-request.jsonand-response.json. The suffix is reserved for messages of a task or operation registered inindex.json, sopackage-request.jsonandpagination-response.jsonget other names. - One file per schema. A schema defined at two paths keeps the path the rules give it, and the other file is deleted. Deleting a copy is a removal, so it goes in 4.0.0 with schemas: give every repeated constraint one definition, and fail CI on any repeat (#8525) #8536, after its referrers are retargeted to the copy that stays. The copy that stays moves in 4.x if the rules put it elsewhere. Two concepts that happen to share a schema stay separate and go in the disposition registry with a reason. The per-task async copies are core/compact-task-submitted composes neither envelope and redeclares four protocol-envelope fields #7919 and The submitted-task envelope is named in core/compact-task-submitted.json and re-declared inline 16 times, each dropping task_id.minLength #8470, and the shared envelope is Catalog envelope-level fields and migrate to allOf shared-envelope pattern #3535.
- The name is the title. The root
titleand the file name say the same words, ignoring case and punctuation, and each file name is used once. Where they differ, the better name wins. A title change keeps the$idand URL but renames the generated type, as The bundle restates 95 object shapes it never titles, over 255 positions in 131 documents — give each one atitle#8735's titles do, so it lands in 4.0.0 with The bundle restates 95 object shapes it never titles, over 255 positions in 131 documents — give each one atitle#8735 and type names change once. A file name change is a move (item 8). When 4.0 retires the legacy twin of acanonical-*schema, the canonical one takes the plain name. - One
$refform. Cross-file refs are/schemas/<path>and target a file root, so a schema used from another file gets its own file. Local refs are#/$defs/<name>(Migrate JSON Schema source from draft-07 to 2019-09 (4.0) #3534). - The build enforces it.
lint-schema-paths.cjschecks all of the above, and the published tree after the build. It blocks new findings from 4.0.0. On main it reports 589 findings in source and 42 in the published tree. They go in a baseline that may only shrink. These are fixed in 4.0.0: the$refform,$defs(with the dialect change, Migrate JSON Schema source from draft-07 to 2019-09 (4.0) #3534), the versioned source ref, the second published copies, duplicate copies and title changes. An extracted schema leaves a$refat its old location, so a pointer to that location still resolves, except a pointer intodefinitions, which changes with the$defsrename. The rest leave the baseline as their moves land. - Moves and file renames land in 4.x, with an alias. The old path keeps a schema that only references the new one (
"allOf": [{ "$ref": "<new path>" }], markeddeprecatedwithx-deprecated-inandx-removed-in: 5.0.0), so old URLs keep resolving and validation doesn't change. The check accepts an alias of this form at the old path. Each file moves once, to the path these rules give it.
Why 4.0
The rules and the check belong with the T2 work in #8756. Without them, every schema added in 4.x picks its own path and name, and the drift above comes back. Moving or renaming a file changes its $id and URL, which breaks every consumer that references it. Under Brian's split on #8359, the moves land in 4.x, and the alias in item 8 keeps each old URL working until 5.0. #8756's Modules row notes that some layering may need file moves and $id renames; this gives them one rule, so each file moves once.
I'm happy to take this on.
Revised 2026-11-12: moves and file renames now land in 4.x, per Brian's split on #8359, each with an alias at the old path. The rules, the check and the fixes that move no file stay in 4.0.0. Counts re-measured on 18da1a4559.
Activity