[Proposal]: Add spec model bindings for integrations and downstream tools

[ramizpolic]

Summary

The AI Catalog specification is defined today as a JSON document format with prose and JSON
Schema, but there are no official, canonically maintained language bindings that downstream
tools can consume. Projects that want to work with AI Catalog documents programmatically must
hand-roll their own models.

A concrete example is AGNTCY Directory (DIR), which maintains its own Protobuf definitions of the
AI Catalog data model (proto/agntcy/dir/catalog/v1/models.proto)
and uses ProtoJSON to serialize/deserialize application/ai-catalog+json documents. This works,
but it is inadequate as a long-term approach: the definitions live outside the spec, must be
manually kept in feature parity with every spec revision (new fields, validation rules, semantic
changes), and any drift silently produces documents that no longer conform. DIR does not want to
own a shadow copy of the spec - it just wants to use the models in code.

TLDR; publish official Protobuf definitions (with ProtoJSON as the wire mapping to the
existing JSON format) as part of the AI Catalog project, so integrations and downstream tools can
generate type-safe bindings in any language instead of each maintaining their own parallel model.

Use cases

1. Registry integrations - Systems like ARD-compliant registries that validate and serve
   AI Catalog documents need typed models that are guaranteed to match the spec
   version they claim to support.
2. Multi-language SDKs for free - Protobuf gives generated bindings for Go, Python,
   TypeScript, Java, Rust, etc. from a single source of truth, without the project having to
   author and maintain per-language SDKs.
3. Validation at the model layer - Constraints from the spec (required fields, URI formats,
   specVersion pattern, url/data mutual exclusivity) can be encoded once (e.g. with
   buf.validate / protovalidate) and enforced identically by every consumer.
4. Toolchain interop - Linters, converters, catalog crawlers, and CI checks can all share the
   same schema artifact instead of each re-implementing the document model.
5. Spec evolution tracking - When a new spec version lands (e.g. new TrustManifest fields),
   consumers upgrade a dependency rather than diffing prose/JSON Schema and patching their own
   models.

Impact

• Interoperability: Without official bindings, every integrator derives its own model from the
  prose spec. Independent implementations inevitably diverge in field optionality, naming, and
  validation, producing documents that "look" conformant but disagree at the edges.
• Maintenance burden: Each downstream project carries the full cost of tracking spec changes.
  DIR's models.proto already re-states the entire spec (catalog, well-known catalog, entries,
  collections, publisher, trust manifest, attestations, provenance) and must be re-audited on
  every spec release.
• Conformance risk: Drift between a downstream model and the spec is silent - there is no
  shared artifact against which conformance can be checked mechanically.
• Adoption friction: New integrators face a "write your own model first" barrier before they
  can do anything useful with AI Catalog documents.

Proposed solutions

Below are some options; this issue is primarily about acknowledging the need for official bindings
rather than prescribing a single approach.

Option A: Adopt Protobuf definitions into the spec repo (preferred)

Host canonical .proto files (e.g. aicatalog/v1/models.proto) in this repository (or a sibling
ai-catalog-proto repo), with:

• ProtoJSON as the normative JSON mapping - the existing application/ai-catalog+json format
  stays exactly as-is; Protobuf is only the schema/codegen source, not a new wire format.
• Validation rules embedded via buf.validate/protovalidate so constraints ship with the
  schema.
• Publishing through the Buf Schema Registry (and/or generated packages) so consumers can
  depend on versioned artifacts.

DIR's existing models.proto already covers the full v1 surface (AICatalog, WellKnownCatalog, CatalogEntry,
CatalogCollection, HostInfo, Publisher, TrustManifest, TrustSchema, Attestation,
ProvenanceLink) and could be donated as a starting point, renamespaced to a spec-owned package.

Option B: Generate bindings from JSON Schema

Keep JSON Schema as the single source of truth and publish generated models per language from it.
This avoids introducing Protobuf but requires the project to run and maintain per-language codegen
pipelines, and loses the uniform validation/annotation story that protovalidate provides.

Option C: Official reference SDK(s)

Hand-written SDKs in one or two flagship languages. Highest per-language quality, but scales
poorly and reintroduces the parity-maintenance problem inside the spec project itself.
Good addition as a follow-up to the schema definitions.

Compatibility notes

• No change to the on-the-wire JSON format or media types; existing documents remain valid.
• CI should verify round-trip fidelity (spec examples ⇄ ProtoJSON) and that the schema matches the
  published JSON Schema for each spec version.

[darrelmiller]

I would like to not do this.

a) we did it in A2A because there was a requirement to support existing HTTP->gRPC translation. No such requirement exists in AI Catalog
b) protobuf cannot capture all the necessary semantics that are in the specification. That means we would now need two "authoritative sources", where either one is duplicative or we need macros to build the specification like we did in A2A.
c) ProtoJSON forces us to do unnatural things like use prefixed SCREAMING_SNAKE_CASE for enum values which is not very natural feeling for most people. This is more important than for A2A because some people will hand author AI Catalog documents.
d) LLMs are quite capable of generating tooling from prose-based specifications.
e) Tooling generated from the .proto will only capture the semantics in the proto and so tooling will be unable to enforce any constraints that are not describable by proto. This will lead to drift in implementations.

[ramizpolic]

Thanks for the feedback @darrelmiller, just want to clarify on a couple of notes:

a) agreed, but for AI Catalog this is not about the translation, but the presentation layer
b, c) protojson when combined with https://protovalidate.com/ can capture (almost?) all the semantics of the spec, including composition rules, validation, and conformance checks. enum rules can also be resolved with https://protovalidate.com/reference/rules/#bufvalidatefieldstringin
e) this is a good point, but i do not see any concrete examples on "not describable by proto". do you have anything specific in mind?

I do think that language-specific SDKs are much better for this, but having a central spec representation in a protojson format does have its advantages