AI Catalog Specification proposal#27
Conversation
Introduces the AI Catalog specification (application/ai-catalog+json) with typed, nestable entries for discovering heterogeneous AI artifacts. Includes Trust Manifest extension for verifiable identity, attestation, and provenance. Adds ReSpec-rendered HTML, CDDL schema, Mermaid diagram, and XML output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Rename Catalog Entry fields per AI Actor Naming Standard (PR #19): - id -> identifier (globally unique logical address) - name -> displayName (human-readable label) Updated in: field definitions, CDDL schema, Mermaid diagram, multi-version rules, trust identity binding, conformance levels, all JSON examples, and OCI/MCP/Claude mapping tables. HostInfo, Publisher, CollectionRef, and TrustSchema retain their existing id/name fields (not agent naming fields). Also updated publish-spec skill to reference renamed markdown file (draft-ai-card.md -> ai-catalog.md). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extend naming alignment to HostInfo, Publisher, CollectionRef, and TrustSchema — not just CatalogEntry. All objects now use identifier for machine-readable IDs and displayName for human-readable labels. Updated: field definitions, CDDL schema, Mermaid diagram, verification procedures, OCI annotations, mapping tables, and all JSON examples. Also simplified publish-spec skill (removed static render step). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Skill entry: use application/ai-skill media type with .zip URL - MCP entry: use /.well-known/mcp/server-card.json path - A2A entry: simplify URL (remove .well-known) - Add edDraftURI linking to PR #18 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
muscariello
force-pushed
the
ai-catalog-spec
branch
from
85ba874 to
e765a1b
Compare
Co-authored-by: Darrel <darrmi@microsoft.com>
muscariello
requested review from
Tehsmash,
ToddSegal,
dsp-ant,
mindpower and
ramizpolic
| specification provides two complementary mechanisms for structuring | ||
| catalogs at scale: **bundles** and **collections**. They serve | ||
| fundamentally different purposes and appear in different parts of | ||
| the document. |
There was a problem hiding this comment.
When reading through this my immediate thought was that these concepts seem to be reversed i.e. it seems natural from a recursive discovery perspective that a catalog could contain a reference to another catalog by catalog media type. But then thinking further it seems confusing that if I hold a catalog object in my hand, I need to know where it came from in the parent to know if its a bundle or collection.
I would look at removing "collections" from the top level catalog, and instead allow catalogs to reference recursive catalogs as entries, and for dependencies handle them at the catalog entry level. For example:
CatalogEntry = {
identifier: text,
....
? dependencies: CatalogEntry
}
This would map well into OCI too without a major change to your proposal, Catalog = OCI Image Index, and Catalog Entry = Image Manifest, config carries metadata, layer[0] can be the "real" card reference, and new part: dependencies maps into layers[1+].
There was a problem hiding this comment.
As discussed during the call. I suggest we leave out bundles as we only care about medaTypes to allow for serialization of the specific card which can be securely referenced in a collection.
Avoid to define dependencies among cards as there is not enough experience on this concept or use in practice.
There was a problem hiding this comment.
Agreed. Based on our discussion, let's remove the bundle concept and dependencies from the spec for now. As you both noted, dependencies are better managed at the individual AI service level, keeping the AI Catalog cleanly focused on discovery.
@muscariello - To align this PR with those notes, we just need to:
- Remove
bundlesand dependencies. - Change the
inlinedata fields todata(as discussed in our meeting).
Do you want to push these updates to this branch, should I push a commit, or we can merge this as-is and handle those two tweaks in a quick follow-up PR? I'm happy to do whatever gets this baseline locked in the fastest!
There was a problem hiding this comment.
@mindpower @ToddSegal Can you please approve?
We intend to merge this to main and create new PRs to address comments.
|
I realize this is likely a file somewhere, but in the case that it's generated dynamically, would allowing pagination the entries make sense? |
5 participants
Summary
This PR brings the AI Catalog specification proposal onto the upstream repository branch
ai-catalog-specand adds a reproducible publication flow for the spec site.Included changes
ai-catalog-specuv-based build command via./build-spec.shValidation
./build-spec.shPublish Specificationcompleted successfully onai-catalog-specGithub Page
https://agent-card.github.io/ai-card/