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

[rvguha]

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.
• ARD base context (§4.1): term IRIs come from a base context (spec/schemas/ard.context.jsonld, served at https://agenticresourcediscovery.org/context/v1) that a conformant consumer applies as the JSON-LD expandContext. @context on the wire stays optional; a plain entry expands correctly under the base context, which also keeps predecessor-format entries valid unchanged.
• 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.

Artifacts ARD now owns

• spec/schemas/ard-entry.schema.json — authoritative for the ARD entry; does not derive from any catalog schema. Defines ardEntry (full), ardEntryProjection (search-result shape), and ardManifest (the /.well-known/ard.json document). additionalProperties is open so namespaced terms stay valid; trustManifest is likewise open (ARD reads only identity).
• spec/schemas/ard.context.jsonld — the base context (§4.1).
• spec/schemas/ard.openapi.yaml — search/list results $ref ardEntryProjection.
• spec/schemas/ard.cddl — start symbol renamed ai-catalog-manifest → ard-manifest.

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.

Review round (addresses @yangbaechu's five comments)

Second commit resolves all five:

1. Base context (§4.1) — a context-less entry previously expanded to [], dropping every core term. Defined the ARD base context applied as expandContext; type→ard:mediaType avoids the @type keyword collision. Verified with a PyLD round-trip (core terms preserved with the context, empty without).
2. trustManifest narrowing — the schema had closed the envelope and dropped trustSchema, silently rejecting valid manifests. Now permissive (additionalProperties: true), trustSchema restored; prose states ARD reads only identity.
3. Signature verification (§4.5.2) — signing, canonicalization, and key resolution are now deferred to the framework named in trustManifest.trustSchema; ARD defines none of its own.
4. ard.json shape (§5.1) — defined as a JSON document with an entries array of ARD entries (ardManifest); CDDL start symbol renamed.
5. Projection retrieval (§5.3.2) — dropped the incorrect "retrievable from url" claim; url addresses the artifact, not the entry; get-by-identifier is out of scope.

Validation

• ard-entry.schema.json compiles; full entry requires representativeQueries, projection requires only identifier, ardManifest accepts an entries array and rejects non-entries, a trustSchema-bearing manifest validates.
• Base context proven by PyLD: plain and extension examples expand with all core terms preserved (incl. mediaType); [] without the context.
• All three §4 example entries validate against ardEntry.
• Footnotes: 25 markers, 25 definitions, no orphans.

Reviewer notes / open items

• The default namespace still supplies the shared terms' meaning; this PR decouples ownership of the ARD entry, 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).
• The CDDL's inner catalog-entry/host-info productions still need reconciling with the new entry model; the JSON Schema is authoritative in the meantime.
• 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.

🤖 Generated with Claude Code

[yangbaechu]

The draft says trustManifest is “As defined by the default namespace” and that ARD does not redefine it, but this schema defines a closed trustManifest object that omits members present in the current ai-catalog definition. For example, an otherwise valid trustManifest containing trustSchema fails validation because it is treated as an additional property.

That appears to be a conformance change despite Identity & Trust being classified as “Structural (no behaviour change).” Was this narrowing intended?

[rvguha]

Not intended — that was a bug, and you're right it wasn't "no behaviour change." Fixed in b3c471b: the schema now leaves trustManifest open (additionalProperties: true) and restores trustSchema, and §4.5 states ARD reads only trustManifest.identity and treats the rest as opaque. A manifest carrying trustSchema now validates.

[yangbaechu]

I ran the plain and extension §4.4 examples as written through PyLD 3.1.0 (jsonld.expand), with no external context.

plain entry (no @context)                       → []
extension example (@context defines acme only)  → only https://acme.com/vocab#serviceTier
                                                       https://acme.com/vocab#region

The PR notes that ai-catalog remains the default vocabulary. For §4.1's "needs no changes" to hold, the draft appears to need a normative mechanism—such as an initial or required base context—that assigns IRIs to inherited and ARD-defined terms and is applied before any local @context. I couldn't find one.

Without it, expansion silently drops every unprefixed core property. The extension example also shows that defining only acme: preserves the extension properties but not the core ones.

If such a context mechanism is already planned, could §4.1 identify it?

[rvguha]

You're right, and thanks for the expansion trace — it's the correct diagnosis. Fixed in b3c471b by defining an ARD base context (spec/schemas/ard.context.jsonld, to be served at https://agenticresourcediscovery.org/context/v1) that a conformant consumer applies as the JSON-LD expandContext (§4.1). It sets @vocab and maps the core terms to IRIs — including type → ard:mediaType, so it no longer collides with the @type keyword. A PyLD round-trip confirms the plain and extension examples now expand with every core term preserved, and still [] without the base context. @context on the wire stays optional; the tradeoff — a plain entry is interpretable only by an ARD-aware consumer that applies the base context — is now stated explicitly.

[yangbaechu]

Appendix D defines the shape of signature, but I couldn't find a normative procedure there for verifying it.

v0.9 sent signature verification and key resolution to ai-catalog. This revision instead points to Appendix D, whose schema describes the fields but does not specify the signed payload, canonicalization, signature processing, or key resolution. Two conforming implementations could therefore make incompatible choices.

Could §4.5.2 identify the normative verification procedure or external reference intended here?

[rvguha]

Correct gap — introduced when the pointer to the predecessor spec was removed. Fixed in b3c471b: §4.5.2 now defers the signed payload, canonicalization, and key resolution to the framework the manifest declares in trustManifest.trustSchema (governanceUri / verificationMethods). ARD mandates only the publisher-authority binding and defines no scheme of its own; a future profile may pin one.

[yangbaechu]

The well-known mechanism in §5.1 points to a manifest at /.well-known/ard.json, but does not define or reference its document shape. The old manifest definition is marked as removed and out of scope, while the CDDL linked from Appendix D still starts with ai-catalog-manifest.

It is therefore unclear whether ard.json is meant to use the legacy { specVersion, host?, entries } envelope or some new entry-source shape. Could §5.1 define or normatively reference the intended top-level structure?

[rvguha]

Fixed in b3c471b. §5.1 now defines the well-known document as a JSON object with an entries array of ARD entries (any other top-level members transport-defined and ignored), formalized as ardManifest in the entry schema. The CDDL start symbol was renamed ai-catalog-manifest → ard-manifest. One follow-up I'll flag: the CDDL's inner catalog-entry / host-info productions still need reconciling with the new entry model; the JSON Schema is authoritative in the meantime.

[yangbaechu]

I don't think url provides the retrieval path this sentence promises.

ardEntryProjection requires only identifier, so a search result need not contain url, and a published entry may use data instead. Even where url is present, §4.3 and the schema define it as a reference to the artifact document—such as an Agent Card or Server Card—rather than to the ARD entry that describes it.

Could §5.3.2 identify an operation or URI that is guaranteed to return the complete ARD entry?

[rvguha]

Agreed on all three counts. Fixed in b3c471b: §5.3.2 no longer claims the entry is retrievable from url. It now states url addresses the artifact (Agent Card / Server Card), not the ARD entry, and that a get-by-identifier retrieval operation is out of scope for this draft.

[yangbaechu]

I read through the draft and left a few inline questions. I may be missing some intended context and would appreciate any corrections.

[rvguha]

Super useful. Thank you. Addressing the comments now.

…

On Fri, Jul 31, 2026 at 5:03 AM yangbaechu ***@***.***> wrote: *yangbaechu* left a comment (ards-project/ard-spec#70) <#70?email_source=notifications&email_token=ABICKCW2VHERO3QAG3GZJCD5HSDIDA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJUGI3DKMJRG4YKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-5142651170> I read through the draft and left a few inline questions. I may be missing some intended context and would appreciate any corrections. — Reply to this email directly, view it on GitHub <#70?email_source=notifications&email_token=ABICKCW2VHERO3QAG3GZJCD5HSDIDA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJUGI3DKMJRG4YKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-5142651170>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABICKCRWFFTERYW6PUDNTOL5HSDIDAVCNFSNUABGKJSXA33TNF2G64TZHMYTENBTG4ZTSMBXGI5US43TOVSTWNJQGEYTAMJVGQYDBILWAI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[yangbaechu]

Thank you for the quick and thorough follow-up. I reviewed the updates, and they address my comments clearly.

[evalstate]

Suggested change

	"minItems": 2,
	"maxItems": 5,

Prefer removing this to allow emitted entries to validate, and flag warnings at the conformance tester

[evalstate]

Do we want this as a conformance warning or hard req (i prefer former).

[mindpower]

We should provide explicit guidance to publishers and stricter rules for consumers regarding whether they should publish as ard.json, or ai-catalog.json or both.

Like:

For Publisher: Add Explicit Publisher Guidance (Informative Addition): Add a paragraph specifically addressing publishers so they know they don't have to duplicate work:

Publisher Guidance (Avoiding Duplication): Publishers do NOT need to host both files. To support both ARD and legacy AI-catalog consumers without duplicating data, publishers are recommended to do one of the following:

• Option A: Host only /.well-known/ard.json and configure the web server to return an HTTP 301 Redirect or use a symlink from /.well-known/ai-catalog.json to ard.json.
• Option B: Continue hosting only /.well-known/ai-catalog.json. Because ARD consumers are required to fallback to this path and apply the ARD base context, the entries will be fully discoverable by both systems.

For consumer: Strengthen Consumer Fallback (Normative Change): Change the consumer requirement to a strict fallback mechanism. e.g.:

• A consumer must attempt to fetch /.well-known/ai-catalog.json if /.well-known/ard.json returns a 404 Not Found.

[mindpower]

Using the word "opaque" here implies that federated registries should treat these fields as a black box that they pass along without inspection. In this case, they won't build the necessary verification pipelines, which defeats the purpose of having a federated, trusted agentic ecosystem in the first place.

Proposed wording (draft): "ARD requires trustManifest.identity for authority binding. The remaining members of the trustManifest are extensible and framework-defined, allowing publishers to use any verifiable trust schema. While ARD does not constrain their structure natively (more examples will be provided later), federated registries are expected to parse and verify these fields according to the declared trust framework to present these trust verification to the consumers"

[rvguha]

I think it should be ard.json since we want them to use namespaces, etc.

…

On Sun, Aug 2, 2026 at 9:31 PM Junjie Bu ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In spec/schemas/ard-entry.schema.json <#70?email_source=notifications&email_token=ABICKCSUJ77BMSZXEPXWWSD5IAISZA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBUGA3TOMRRGA4KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K64DSL5ZGK5TJMV3V6Y3MNFRWW#discussion_r3701305255> : > + "not": { "required": ["data"] } + }, + { + "required": ["data"], + "not": { "required": ["url"] } + } + ] + }, + "ardEntryProjection": { + "description": "An ARD entry as returned in search results — a projection carrying the terms useful for selecting among results. Only `identifier` is required; a registry MAY omit any other term, notably `representativeQueries`, which serve indexing rather than presentation. `identifier` names the authoritative entry; the full entry is obtained from the source that published it.", + "allOf": [{ "$ref": "#/$defs/entryFields" }], + "required": ["identifier"] + }, + "ardManifest": { + "type": "object", + "description": "The document published at /.well-known/ard.json (or any entry source). ARD requires only an `entries` array of ARD entries; any other top-level members are transport-defined and ignored by ARD, so additionalProperties is open.", We should provide explicit guidance to publishers and stricter rules for consumers regarding whether they should publish as ard.json, or ai-catalog.json or both. Like: *For Publisher*: Add Explicit Publisher Guidance (Informative Addition): Add a paragraph specifically addressing publishers so they know they don't have to duplicate work: Publisher Guidance (Avoiding Duplication): Publishers do NOT need to host both files. To support both ARD and legacy AI-catalog consumers without duplicating data, publishers are recommended to do one of the following: - Option A: Host only /.well-known/ard.json and configure the web server to return an HTTP 301 Redirect or use a symlink from /.well-known/ai-catalog.json to ard.json. - Option B: Continue hosting only /.well-known/ai-catalog.json. Because ARD consumers are required to fallback to this path and apply the ARD base context, the entries will be fully discoverable by both systems. *For consumer*: Strengthen Consumer Fallback (Normative Change): Change the consumer requirement to a strict fallback mechanism. e.g.: - A consumer must attempt to fetch /.well-known/ai-catalog.json if /.well-known/ard.json returns a 404 Not Found. ------------------------------ In spec/ard-v0.91-draft.md <#70?email_source=notifications&email_token=ABICKCSUJ77BMSZXEPXWWSD5IAISZA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBUGA3TOMRRGA4KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K64DSL5ZGK5TJMV3V6Y3MNFRWW#discussion_r3701326086> : > +| displayName | MUST | Human-readable name. | +| type | MUST | Artifact type as an IANA Media Type (§3.3). | +| url _or_ data | MUST (exactly one) | Value-or-reference (§4.3). | + +An ARD entry SHOULD additionally carry `representativeQueries`, and `capabilities` is recommended where it applies; these are the discovery signals, so they are described in full here rather than by reference. + +| Term | Requirement | Description | +| :--- | :--- | :--- | +| representativeQueries | SHOULD | Sample natural-language queries a user might issue that this resource can serve — the signal a registry builds its semantic index from. An entry without it cannot be found by search, which is what distinguishes an ARD entry from a bare catalog entry. SHOULD contain 2–5 examples. It is not hard-required: the schema does not reject an entry that omits it or supplies a different count — the conformance tester flags those as warnings (§D.2), so output from existing tooling still validates.[^reqqueries] | +| capabilities | MAY | Short skill or tool tokens (e.g. `["WeatherTool"]`) enabling fast structured filtering without fetching the full artifact. | + +The remaining terms are optional and descriptive. + +| Term | Description | +| :--- | :--- | +| description, tags, version, updatedAt, metadata, trustManifest | Descriptive terms. `trustManifest` is discussed in §4.5; ARD reads only `trustManifest.identity` and treats the rest as opaque. | Using the word "opaque" here implies that federated registries should treat these fields as a black box that they pass along without inspection. In this case, they won't build the necessary verification pipelines, which defeats the purpose of having a federated, trusted agentic ecosystem in the first place. Proposed wording (draft): "ARD requires trustManifest.identity for authority binding. The remaining members of the trustManifest are extensible and framework-defined, allowing publishers to use any verifiable trust schema. While ARD does not constrain their structure natively (more examples will be provided later), federated registries are expected to parse and verify these fields according to the declared trust framework to present these trust verification to the consumers" — Reply to this email directly, view it on GitHub <#70?email_source=notifications&email_token=ABICKCQI2Y4MGAB6PJGEYIT5IAISZA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIOBUGA3TOMRRGA4KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2L24DSL5ZGK5TJMV3V63TPORUWM2LDMF2GS33OONPWG3DJMNVQ#pullrequestreview-4840772108>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABICKCQ2AY2NZRX6WFKQBKT5IAISZAVCNFSNUABGKJSXA33TNF2G64TZHMYTENBTG4ZTSMBXGI5US43TOVSTWNJQGEYTAMJVGQYDBILWAI> . You are receiving this because you authored the thread.Message ID: ***@***.***>