Skip to content

Add ARD v0.91 draft: define the ARD entry, decouple from ai-catalog - #70

Open
rvguha wants to merge 1 commit into
mainfrom
ard-v0.91-draft
Open

Add ARD v0.91 draft: define the ARD entry, decouple from ai-catalog#70
rvguha wants to merge 1 commit into
mainfrom
ard-v0.91-draft

Conversation

@rvguha

@rvguha rvguha commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

What this is

Adds the v0.91 draft (spec/ard-v0.91-draft.md) alongside the published v0.9 (spec/ard.md is untouched). The draft is annotated with editorial footnotes and ◆ breadcrumbs marking every change from v0.9; an editorial box at the top explains the conventions. All annotations are review aids and are to be removed before publication.

Headline change: ARD defines the ARD entry

§4 establishes that the ARD entry is a distinct object from a catalog entry, with a different obligation — a catalog accommodates whatever a publisher lists; an ARD entry guarantees the signals a search service needs. The normative formulation:

Every ARD entry is a well-formed catalog entry, but not every catalog entry is an ARD entry.

Because the definitions are separate, each spec's conformance is self-contained: a future reduction of any catalog core cannot silently change what ARD requires.

Normative changes (flagged in place)

  • representativeQueries is now REQUIRED for an ARD entry (§4.2). It is the signal the semantic index is built from; an entry lacking it cannot be found by search. A listing without it remains a valid catalog entry — just not an ARD entry.
  • Well-known path / link relation are now ard-named: /.well-known/ard.json, rel="ard" (§5.1). The former ai-catalog names are honoured as aliases (Compatibility note), so nothing published today breaks.

New artifact: ARD owns its entry schema

  • spec/schemas/ard-entry.schema.json — authoritative for the ARD entry, does not derive from any catalog schema. Structure: entryFields (open, additionalProperties: true so namespaced terms stay valid) → ardEntry (full, requires the discovery terms + value-or-reference) and ardEntryProjection (search-result shape, only identifier required, so results may omit representativeQueries).
  • spec/schemas/ard.openapi.yaml — search/list result $refs repointed to ardEntryProjection.

Structural (no behaviour change)

  • Description layer restated on JSON-LD with a default namespace + @context extension seam.
  • Identity & Trust folded into the entry model (§4.5).
  • Discovery reorganized as the umbrella over the search API and federation.

Validation

  • ard-entry.schema.json compiles; full entry requires representativeQueries, projection does not, namespaced extra terms accepted.
  • All three §4 example entries validate against the required terms + value-or-reference.
  • Footnotes: 24 markers, 24 definitions, no orphans.

Reviewer notes / open items

  • The default namespace still supplies term definitions (ai-catalog as default); this PR decouples ownership, not the default vocabulary. Remaining ai-catalog mentions in the publishable body: one Compatibility note (unavoidable — you can't alias a name without naming it).
  • conformance/bin/conformance-test still loads the catalog schema and validates whole manifests; it needs a separate change to iterate entries[] against ard-entry.schema.json. Deliberately not included here.
  • The generated .docx is intentionally excluded (build artifact).

🤖 Generated with Claude Code

…talog

Adds the v0.91 draft alongside the published v0.9 (ard.md is unchanged).
The draft is annotated with editorial footnotes/breadcrumbs marking every
change from v0.9, for review; these are to be removed before publication.

Substantive changes:
- §4 establishes that ARD defines the ARD entry as a distinct object from a
  catalog entry. Every ARD entry is a well-formed catalog entry, but not
  every catalog entry is an ARD entry; the two specs' conformance is
  self-contained.
- representativeQueries is now REQUIRED for an ARD entry (§4.2): it is the
  signal the semantic index is built from, so an entry lacking it cannot be
  found by search.
- New authoritative schema spec/schemas/ard-entry.schema.json, owned by ARD
  (does not derive from any catalog schema). OpenAPI entry $refs repointed
  to it.
- Well-known path and link relation are now ard-named (/.well-known/ard.json,
  rel="ard"); the former ai-catalog names are honoured as aliases so nothing
  published today breaks.
- Description layer restated on JSON-LD with a default namespace and a
  @context extension seam; Identity & Trust folded into the entry model;
  Discovery reorganized as the umbrella over the search API and federation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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