Add ARD v0.91 draft: define the ARD entry, decouple from ai-catalog - #70
Open
rvguha wants to merge 1 commit into
Open
Add ARD v0.91 draft: define the ARD entry, decouple from ai-catalog#70rvguha wants to merge 1 commit into
rvguha wants to merge 1 commit into
Conversation
…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>
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.
What this is
Adds the v0.91 draft (
spec/ard-v0.91-draft.md) alongside the published v0.9 (spec/ard.mdis 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:
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)
representativeQueriesis 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.ard-named:/.well-known/ard.json,rel="ard"(§5.1). The formerai-catalognames 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: trueso namespaced terms stay valid) →ardEntry(full, requires the discovery terms + value-or-reference) andardEntryProjection(search-result shape, onlyidentifierrequired, so results may omitrepresentativeQueries).spec/schemas/ard.openapi.yaml— search/list result$refs repointed toardEntryProjection.Structural (no behaviour change)
@contextextension seam.Validation
ard-entry.schema.jsoncompiles; full entry requiresrepresentativeQueries, projection does not, namespaced extra terms accepted.Reviewer notes / open items
ai-catalogmentions in the publishable body: one Compatibility note (unavoidable — you can't alias a name without naming it).conformance/bin/conformance-teststill loads the catalog schema and validates whole manifests; it needs a separate change to iterateentries[]againstard-entry.schema.json. Deliberately not included here..docxis intentionally excluded (build artifact).🤖 Generated with Claude Code