Conversation
… warning The warning on a root 'collections' property, and the matching line in conformance/README.md, tell the reader that the removal is recorded in ADR-0003. ADR-0003 is adr/0003-urn-placeholder-rfc2606-alignment.md and is about RFC 2606 placeholders in URNs; no ADR records the removal of top-level collections. The reference has never resolved. It was introduced on 2026-05-20 in 1caf78d, when the adr/ directory did not yet exist. The first ADRs were added six days later, on 2026-05-26, and 0003 went to the URN placeholder decision, where it has stayed. Nothing was renumbered and no ADR file has ever been deleted or renamed. The removal itself is real and is recorded in 5e9d3ef, "spec: remove top-level collections array in favor of nested catalog entries", which dropped the array from the specification, the CDDL and the JSON Schema. This removes the reference rather than replacing it, so the sentence no longer points at a document that does not describe it. The guidance is unchanged: hierarchies should be modeled inside 'entries'.
frmoretto
requested review from
evalstate,
mindpower and
rvguha
as code owners
September 25, 2026 06:31
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The warning about a root
collectionsproperty tells the reader that the removal isrecorded in ADR-0003. ADR-0003 is about RFC 2606 placeholders in URNs, and no ADR
records the removal of collections at all, so a reader who follows the pointer finds
a document about something else. The reference has already spread: two open items
already cite ADR-0003 when what they mean is the collections rule.
This PR removes the reference from the two places that carry it. It does not replace
it with another citation and does not propose an ADR, both of which would be
decisions for the authors rather than a documentation fix. The sentence stands on its
own without it, because it already says what a publisher should do instead: model
hierarchies inside
entries.Detail
The reference has never resolved, rather than having gone stale.
1caf78d, the commit that added the conformanceCLI. At that commit the
adr/directory did not exist and there were no ADR filesin the repository.
a257952(0001, 0002,0004) and
e86578e(0003, the URN placeholder decision).adr/0003-*has beenabout RFC 2606 placeholders since it was created, and
git log --followshows onlythree commits, all on that subject.
git log --all --diff-filter=Dand--diff-filter=Rfindreal deletions and renames elsewhere in the repository and none under
adr/.5e9d3efof 2026-05-20, "spec: removetop-level collections array in favor of nested catalog entries", which dropped it
from
spec/agentfinder.md, the CDDL andai-catalog.schema.json. That commitmessage also carries the
(ADR-0003)designation, on the same day and withadr/equally absent.
The two occurrences.
conformance/bin/conformance-test, line 382, theadd_warningtext.conformance/README.md, line 96, the Legacy Field Detection bullet.spec/urn-naming-guide.mdalso cites ADR-0003, correctly, for the placeholderguidance. That one is not touched.
The reference has propagated.
nested
application/ai-catalog+jsonentries withurl, no rootcollectionsarray".
Both use the number to mean the collections rule. Leaving the reference in place
keeps producing this.
Test plan
No test or fixture asserts this string:
collectionsandADR-0003do not appearanywhere under
conformance/tests/orconformance/examples/.python -S ./conformance/bin/conformance-test manifest ./conformance/examples/basic/ard.json:CONFORMANCE STATUS: PASS, 0 errors and 2 warnings, exit 0python -S ./conformance/tests/test_media_type_diagnostics.py -v: Ran 19 tests, OKpython -S ./conformance/bin/conformance-test manifest ./conformance/tests/fixtures/extension-media-types.json:PASS, 0 errors, 3 warnings, 3 informationalARD_REQUIRE_JSONSCHEMA=1: Ran 19 tests, OK"collections": []added toexamples/basic/ard.jsonstillproduces the warning and still passes, with the corrected text
Identical results before and after the change. Documentation and one warning string
only; no behaviour, schema or specification change.