Resolve #58: Add ADR-0017 and migrate to namespace extensions map by mindpower · Pull Request #77 · Agent-Card/ai-catalog

mindpower · 2026-07-10T23:53:53Z

Summary

This PR formally resolves Issue #58 (Proposal for JSON-LD @context Namespaces) by implementing the consensus reached during the July 2 and July 9 Working Group meetings and also comments on that issue.

To preserve the AI-Catalog's minimalist parser and avoid the complexity of JSON-LD graph resolution, the TSC agreed to reject the @context proposal. Instead, we are adopting a loosely coupled architecture with the Agentic Resource Discovery (ARD) specification and replacing the legacy metadata property with a strict extensions array.

Changes Included

Added ADR-0017: Documents the decision to loosely couple ARD and AI-Catalog, preserving AI-Catalog as a strictly-typed "publishing format" while allowing ARD to evolve independently as a rich "discovery format."
Updated ai-catalog.md:
- Removed the legacy metadata property from the Catalog Entry, Trust Manifest, and root schemas.
- Introduced the extensions array mechanism.
- Rewrote the Extensibility section to enforce reverse-DNS/URL keys for extension boundaries.

Motivation

This architecture allows AI-Catalog to remain a lightweight, fast "thin pointer," while freeing downstream aggregators (like ARD) to build the complex semantic envelopes they need for federated discovery without forcing those requirements into the base protocol.

Closes #58

github-actions · 2026-07-10T23:54:28Z

Preview: https://ai-catalog.io/pr/77/

This comment is updated automatically while the pull request preview is available.

tadasant · 2026-07-16T15:19:15Z

-## Value Types
+1. **Metadata** (`https://ai-catalog.org/extensions/metadata`)
+   - Used to store generic, schemaless key-value pairs (replacing the legacy metadata field).
+2. **SBOM** (`https://ai-catalog.org/extensions/sbom`)


Do we want to add SBOM out of the gate? Alternatively: we just have the metadata field and add to it if we see ecosystem adoption of specifics

I would expect SBOM to be a trust attestation type rather than included in metadata

darrelmiller · 2026-07-16T15:33:08Z

+After extensive discussions in the July 2 and July 9, 2026 working group meetings, the team concluded that the requirements of the two projects are fundamentally different. ARD requires the ability to aggregate rich, namespaced descriptions of resources directly in the discovery payload, while AI-Catalog requires strict, minimal schema definitions.
+
+## Decision
+The ARD (Agentic Resource Discovery) specification will be **loosely coupled** with the AI-Catalog specification. 


Let's just remove this line so it doesn't look like we are making decisions on behalf of the ARD group.

@context

…, and migrate metadata to extensions array This commit formalizes the resolution to Issue #58 regarding extensibility and JSON-LD namespaces. Based on working group consensus (July 9, 2026), we are adopting a loosely coupled architecture with ARD to preserve AI-Catalog's minimalist parser. Changes included: - Added ADR-0017 to formally document the rejection of JSON-LD @context and the decision to loosely couple the ARD specification. - Updated `specification/ai-catalog.md` to remove the legacy `metadata` property across Catalog Entry and Trust Manifest schemas. - Replaced the Extensibility section with the new `extensions` array design, enforcing URL/reverse-DNS keys for vendor-specific fields.

mindpower · 2026-07-22T22:02:43Z

Thanks for all the feedback and suggestions! I've updated the PR to reflect that. Here is a summary of the changes:

Changed extensions to a Map: Following the discussion, I've updated the spec (including the CDDL schema) to define extensions as a JSON object (map) instead of an array. This makes it easier to manage and parse namespace keys.
Removed SBOM Example: I removed the SBOM from the "Official Extensions" list to keep the core spec examples as lightweight as possible.
Remove the sentence : "ARD will be loose coupling with AI-catalog" on the adr-0017 -> this is on ARD spec side.
Added Example for Map Structure: I included a concrete JSON example in the Format and Key Naming section to demonstrate how the new map structure cleanly handles namespaces (e.g., encapsulating metadata and custom okf schemas directly within the extensions map).

Example:
For example, a catalog entry with extensions representing metadata and a custom schema:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:treasury.gov:okf:fiscaldata",
      "type": "text/vnd.okf+markdown",
      "tags": ["finance", "treasury"],
      "extensions": {
        "metadata": {
          "location": "US-West",
          "environment": "staging",
          "version-compatible": [">=1.0.0"]
        },
        "okf": {
          "@context": "https://openknowledgeformat.org/ns#",
          "type": "Financial Dataset",
          "taxonomy": "us-gaap",
          "conformsTo": ["us-gaap:Revenue", "ifrs:Revenue"]
        }
      }
    }
  ]
}

Let me know what you think of the new structure!

tadasant

Looks great to me, thanks for iterating @mindpower !

Tehsmash

Two tiny requests, otherwise LGTM.

Tehsmash · 2026-07-23T11:49:49Z

+      "type": "text/vnd.okf+markdown",
+      "tags": ["finance", "treasury"],
+      "extensions": {
+        "metadata": {


We should make sure this example is compliant with: "To avoid collisions between independent publishers, the keys MUST be a valid URL or a reverse-DNS string"

Suggested change

"metadata": {

"https://ai-catalog.org/extensions/metadata": {

Tehsmash · 2026-07-23T11:50:09Z


-## Value Types
+1. **Metadata** (`https://ai-catalog.org/extensions/metadata`)
+   - Used to store generic, schemaless key-value pairs (replacing the legacy metadata field).


No need to mention "legacy" IMO unless we're doing official deprecations of existing fields as part of the spec.

Suggested change

- Used to store generic, schemaless key-value pairs (replacing the legacy metadata field).

- Used to store generic, schemaless key-value pairs.

darrelmiller · 2026-07-23T13:13:51Z

LGTM with the minor changes suggested by Sam.

ramizpolic · 2026-07-23T14:23:36Z

LGTM with the minor changes suggested by Sam.

+1

mindpower requested a review from a team as a code owner July 10, 2026 23:53

github-actions Bot added a commit that referenced this pull request Jul 10, 2026

Publish specification preview for PR #77

5b3ed15

Wolfe-Jam mentioned this pull request Jul 13, 2026

Proposal: Replace nested metadata with JSON-LD style @context and namespaced fields #58

Open

darrelmiller reviewed Jul 16, 2026

View reviewed changes

Comment thread specification/ai-catalog.md Outdated

tadasant reviewed Jul 16, 2026

View reviewed changes

darrelmiller reviewed Jul 16, 2026

View reviewed changes

jonathanhefner reviewed Jul 16, 2026

View reviewed changes

Comment thread specification/ai-catalog.md Outdated

Comment thread adr/0017-ard-loose-coupling.md

tadasant mentioned this pull request Jul 20, 2026

Add experimental Server Cards support (SEP-2127) modelcontextprotocol/python-sdk#2951

Draft

mindpower force-pushed the mindpower/loose-coupling branch from 6a70372 to e79245d Compare July 22, 2026 21:49

github-actions Bot added a commit that referenced this pull request Jul 22, 2026

Publish specification preview for PR #77

bbb8f74

updated the extension spec based on latest discussion

44bd400

github-actions Bot added a commit that referenced this pull request Jul 22, 2026

Publish specification preview for PR #77

e0f777e

mindpower changed the title ~~Resolve #58: Add ADR-0017 (Loose Coupling) and migrate to extensions array~~ Resolve #58: Add ADR-0017 and migrate to namespace extensions map Jul 22, 2026

tadasant approved these changes Jul 23, 2026

View reviewed changes

Tehsmash suggested changes Jul 23, 2026

View reviewed changes

	"metadata": {
	"https://ai-catalog.org/extensions/metadata": {

	- Used to store generic, schemaless key-value pairs (replacing the legacy metadata field).
	- Used to store generic, schemaless key-value pairs.

Uh oh!

Conversation

mindpower commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes Included

Motivation

Uh oh!

github-actions Bot commented Jul 10, 2026

Uh oh!

Uh oh!

tadasant Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Tehsmash Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

darrelmiller Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mindpower commented Jul 22, 2026

Uh oh!

tadasant left a comment

Choose a reason for hiding this comment

Uh oh!

Tehsmash left a comment

Choose a reason for hiding this comment

Uh oh!

Tehsmash Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Tehsmash Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

darrelmiller commented Jul 23, 2026

Uh oh!

ramizpolic commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mindpower commented Jul 10, 2026 •

edited

Loading