Resolve #58: Add ADR-0017 (Loose Coupling) and migrate to extensions array

[mindpower]

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

1. 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."
2. 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]

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

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

[darrelmiller]

@mindpower Let's discuss the map versus array decision here.

[Tehsmash]

As mentioned in the call, I want to understand why we want an array, it introduces new ambiguity around duplicate entries etc. I prefer a map unless we explicitly want to support duplicate entries of the same extension.

I could see scenarios where it might be useful to have multiple items of the same extension, but all of those cases could also be push down a level into the extension itself. For example:

extensions: [
   {
       "type": "foo.org/score/v1"
       "source": "baz",
       "score": 123
    },
    {
       "type": "foo.org/score/v1"
       "source": "bar",
       "score": 123
    },
] 

extensions: {
    "foo.org/score/v1" {
    	"scores": {
    		"baz": 123
			"bar": 123
       	}
    }
} 

[tadasant]

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

[Tehsmash]

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

[darrelmiller]

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

[jonathanhefner]

Just dropping a comparison:

{
  "extensions": [
    {
      "type": "foobar",
      "data": {
        "key": "value"
      }
    }
  ]
}

vs:

{
  "extensions": {
    "foobar": {
      "key": "value"
    }
  }
}

To my human eyes, the latter is easier to read. Though perhaps the former is easier to consume programmatically?

Also, as @Tehsmash pointed out during the meeting, the latter prevents duplicate extensions by construction.

[jonathanhefner]

I might be missing something, but I feel like the extension mechanism proposed in this PR is compatible with ARD's proposed @context mechanism.

The example they give is:

{
  "specVersion": "1.0",
  "entries": [
    {
      "@context": {
        "okf": "https://openknowledgeformat.org/ns#",
        "us-gaap": "https://xbrl.fasb.org/us-gaap/",
        "ifrs": "https://xbrl.ifrs.org/taxonomy/"
      },
      "identifier": "urn:air:treasury.gov:okf:fiscaldata",
      "type": "text/vnd.okf+markdown",
      "tags": ["finance", "treasury"],
      "okf:type": "Financial Dataset",
      "okf:taxonomy": "us-gaap",
      "okf:conformsTo": ["us-gaap:Revenue", "ifrs:Revenue"]
    }
  ]
}

Which can be equivalently expressed as:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:treasury.gov:okf:fiscaldata",
      "type": "text/vnd.okf+markdown",
      "tags": ["finance", "treasury"],
      "extensions": [
        {
          "type": "ard",
          "data": {
            "@context": {
              "okf": "https://openknowledgeformat.org/ns#",
              "us-gaap": "https://xbrl.fasb.org/us-gaap/",
              "ifrs": "https://xbrl.ifrs.org/taxonomy/"
            },
            "okf:type": "Financial Dataset",
            "okf:taxonomy": "us-gaap",
            "okf:conformsTo": ["us-gaap:Revenue", "ifrs:Revenue"]
          }
        }
      ]
    }
  ]
}

(Not to dwell on ARD's design decisions. Just wanted to point this out to justify our design decision.)