Skip to content

docs(conformance): remove the ADR-0003 reference from the collections warning - #100

Open
frmoretto wants to merge 1 commit into
ards-project:mainfrom
frmoretto:conformance-collections-adr-reference
Open

frmoretto wants to merge 1 commit into
ards-project:mainfrom
frmoretto:conformance-collections-adr-reference

Conversation

@frmoretto

Copy link
Copy Markdown

Summary

The warning about a root collections property tells the reader that the removal is
recorded 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.

  • It was introduced on 2026-05-20 in 1caf78d, the commit that added the conformance
    CLI. At that commit the adr/ directory did not exist and there were no ADR files
    in the repository.
  • The first ADRs were added six days later, on 2026-05-26, in a257952 (0001, 0002,
    0004) and e86578e (0003, the URN placeholder decision). adr/0003-* has been
    about RFC 2606 placeholders since it was created, and git log --follow shows only
    three commits, all on that subject.
  • Nothing was renumbered. git log --all --diff-filter=D and --diff-filter=R find
    real deletions and renames elsewhere in the repository and none under adr/.
  • The removal of collections is recorded, in 5e9d3ef of 2026-05-20, "spec: remove
    top-level collections array in favor of nested catalog entries", which dropped it
    from spec/agentfinder.md, the CDDL and ai-catalog.schema.json. That commit
    message also carries the (ADR-0003) designation, on the same day and with adr/
    equally absent.

The two occurrences.

  • conformance/bin/conformance-test, line 382, the add_warning text.
  • conformance/README.md, line 96, the Legacy Field Detection bullet.

spec/urn-naming-guide.md also cites ADR-0003, correctly, for the placeholder
guidance. That one is not touched.

The reference has propagated.

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: collections and ADR-0003 do not appear
anywhere under conformance/tests/ or conformance/examples/.

  • python -S ./conformance/bin/conformance-test manifest ./conformance/examples/basic/ard.json: CONFORMANCE STATUS: PASS, 0 errors and 2 warnings, exit 0
  • python -S ./conformance/tests/test_media_type_diagnostics.py -v: Ran 19 tests, OK
  • python -S ./conformance/bin/conformance-test manifest ./conformance/tests/fixtures/extension-media-types.json: PASS, 0 errors, 3 warnings, 3 informational
  • the same with ARD_REQUIRE_JSONSCHEMA=1: Ran 19 tests, OK
  • a manifest with "collections": [] added to examples/basic/ard.json still
    produces 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.

… 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'.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant