Variant proposal

[darrelmiller]

Starting with the #4 here is an updated proposal. Sorry for the CDDL, it's just a lot more compact to work with. If only GitHub did syntax highlighting.

; The unified AI Card object for any AI related service
AICard = {
  $schema: text,              ; Declares the schema this card adheres to (e.g., "https://ai-AI Card-protocol.org/ai-card/v1/schema.json")
  id: text,                   ; The primary verifiable ID for the AI Card (e.g., DID)
  name: text,                 ; A human-readable name for the AI Card
  description: text,          ; A short, human-readable description of the AI Card's purpose
  ? logoUrl: text,            ; A direct URL to the AI Card's logo image. Could be a data URL or an HTTPS URL.
  ? tags: [* text],           ; A list of keywords to aid in discovery
  publisher: {
    id: text,                 ; A verifiable ID for the publisher, e.g., a DID or organization ID
    name: text,               ; The human-readable name of the publisher
    ? attestations: [* Attestation]   ; A list ofverifiable credentials (e.g., JWT) asserting the publisher's credibility
  },
  ? attestations: [* Attestation]  ; A list of compliance or other attestations for AI Card
  createdAt: text,            ; An ISO 8601 timestamp of when the AI Card was first published
  updatedAt: text,            ; An ISO 8601 timestamp of when this card was last updated
  ? metadata: {* metadata-key => any}, ; An open "black box" for any other non-standard metadata
  ? maturity: ("preview" / "stable" / "deprecated"), ; AI Card lifecycle stage
  ? signature: text,  ; Detached JWS compact serialization (<header>..<signature>) signing the canonical card content

  services: {* service-type => any},  ; Map of interaction protocols this AI Card supports, keyed by protocol type
}

; Service type choices
service-type = "mcp" / "a2a" / text

; Well-known metadata key choices
metadata-key = "privacyUrl" / "termsOfUseUrl" / "supportUrl" / "documentationUrl" / "version" / text

; A single compliance, security, or custom attestation
Attestation = {
  type: text,               ; The type of attestation (e.g., "SOC2", "HIPAA", "CustomBadge")
  ? badgeUrl: text,         ; (Low-Trust) A URL to a simple JSON "badge" file
  ? credentialUrl: text,    ; (High-Trust) A URL to a verifiable credential (e.g., a JWT or PDF report); use when credential is large or hosted remotely
  ? credentialValue: text   ; (High-Trust) The embedded, base64-encoded credential itself (e.g., a JWT); use for self-contained attestations
}

; The AI Catalog served from /.well-known/ai-catalog.json
AICatalog = {
  $schema: text,           ; Declares the schema this catalog adheres to
  host: {
    name: text,                 ; The human-readable name of the host (e.g., the company name)
    ? id: text,                 ; A verifiable ID for the host (e.g., a DID)
    ? documentationUrl: text,   ; A URL to the host's main documentation
    ? logoUrl: text             ; A URL to the host's logo
  },
  aiCards: [* {
    id: text,             ; The primary verifiable ID for the AI Card (e.g., DID); must match the 'id' in the full AICard
    name: text,           ; A human-readable name for the AI Card
    description: text,    ; A short description of the AI Card
    ? tags: [* text],     ; A list of tags for filtering and discovery
    cardUrl: text         ; The full, absolute URL to this AI Card's complete ai-card.json file
    updatedAt: text      ; An ISO 8601 timestamp of when this card was last updated
  }]
}

Changes:

• Removed specVersion because $schema can do the same job
• Made publisher attestation a list of Attestation type, same as how the AI Card has attestations
• Removed the trust property and type because identity is already provided by id, and the typeisn't necessary becausedidandspiffe` both have uri schemes
• Added some predefined keys for metadata for things we know may be commonly used but don't really need to be schematized.
• Added a maturity property as that seems like something crawlers and registries are going to care about
• Added a signature property because we need to tie the id of the publisher to the card contents.
• Changed services to be a map of any with some predefined keys.
• Added updatedAt to the aiCard in the catalog

Would love to get people's thoughts on the changes.

[mindpower]

Thanks for writing this up! This looks like a great convergence.

I'm glad we are aligned on the Catalog (List) + Card (Detail) architecture. That separation is critical for the scalability and identity isolation reasons we discussed.

Regarding the schema specifics, here are my thoughts on merging the two approaches:

1. Services: Map vs. Array (Agree with Map)

Moving services to a Map (service-type => payload) is a great idea. It simplifies the JSON structure and makes client lookups (card.services['a2a']) O(1) and cleaner than iterating an array. I'm happy to update the PR to this.

2. Identity & Trust (Prefer Grouping)

I would advocate for keeping the trust object wrapper rather than flattening attestations to the root.

• Organization: As we add more security fields (like signature, privacyPolicyUrl, termsOfServiceUrl), the root object will get very crowded. Grouping them under trust keeps the "Business Logic" (services/skills) separate from the "Security Context."
• Explicit Identity: While id technically contains the URI, keeping an explicit trust.identity object allows us to pass that object directly to verification libraries without them needing to parse the full card.

3. Versioning (Prefer keeping specVersion - please also see comments on #4)

I'd strongly suggest we keep specVersion alongside $schema.

• Reason: $schema is for validators (machine-readable). specVersion is for client logic (human-readable logic like if version >= 1.2). Decoupling them prevents us from breaking validation just to signal a minor feature update.

4. Signature & Maturity (Agree)

Adding signature (JWS) and maturity are excellent additions.

Next Steps:
I can update PR #4 to reflect the Map-based Services and add the Signature/Maturity fields, while keeping the trust grouping for organization. Does that sound like a good path forward?

[mindpower]

I have updated PR #4 to incorporate the discussed changes (Map-based services, Identity object, etc.).

I've also added the CDDL specifications as requested to make the structure easier to review. You can view the spec files and examples here:

• ai-card spec in CDDL
• ai-catalog spec in CDDL
• ai-card-example
• ai-catalog-example

[darrelmiller]

@mindpower I don't feel strongly about the specVersion, so if you prefer to keep it separate then that's fine. I would highly recommend not including the patch in the version. We really regretted that in OpenAPI. Patch versions are usually just for editorial updates for the specification document and including them in the actual ai card document will likely just create confusion.

With the additional properties you have added to Trust, I agree that having that grouping makes sense. I'm still not sure I understand your point about the Identity property. Are you suggesting being able to pass the entire "Trust" object to a verification library?

I'm not convinced we still need the baseService object. I'm not sure we can lift AgentEndpoint up into baseService. There is currently discussion about adding another scope/instance property into that endpoint. Also, in A2A we are not using the term transport anymore. And the authentication property would need to be an array of "Security Requirement" objects to properly map to OpenAPI. In A2A there was a discrepancy between how the TypeScript was defined and the proto.

I guess my main point is I think this is going to be a challenging set of properties to get agreement across different protocols. It would be great if we could, but I think it will be hard.

[mindpower]

@darrelmiller Thanks for the detailed feedback. Here is my proposal to address them:

1. specVersion (Agreed: Major.Minor only) Including patch versions in the document creates unnecessary churn. I will update the spec to explicitly state that specVersion should strictly follow Major.Minor format (e.g., "1.0"), where patch updates to the spec text do not require changes to the JSON artifact.
2. trust.identity (Clarification) I initially thought the verification library could simply accept the trust object without needing the root ID separately. However, in practice, developers almost always pass the entire object to a verification function. I agree this redundancy is unnecessary. I will simplify the structure as follows:
   • Remove: trust.identity
   • Add: identityType (at root, optional/helper).
   • Update: Publisher now uses id directly instead of a nested id object, matching the root structure. and adds the optional identityType helper field.
3. baseService & Alignment (The Pivot: Make it Thinner), I agree that getting alignment on transport/auth details across different protocols will be challenging. Proposal: I will significantly thin down the BaseService definition in the core spec.
   • Remove: endpoints, transport, and authentication from the top-level BaseService.
   • Move Down: Let each protocol define these inside their protocol Specific payload (or the service object itself).
   • Retain Wrapper: However, I prefer keeping the BaseService structure (wrapping protocolSpecific) rather than dropping to raw any, The reason is Namespace Isolation. By keeping a thin wrapper, we reserve a space for future common metadata (like a healthCheckUrl, status badge, or at minimal a human-readable name for the interface) that applies to all services, regardless of protocol.

Here is the updated spec:

; ============================================================================
; AI Card Specification (v1)
; ============================================================================

AICard = {
  $schema: text,              ; URI to the JSON schema
  specVersion: text,          ; e.g. "1.0", Major.Minor version only, no patch
  
  ; --- Identity (Subject) ---
  id: text,                   ; Globally unique ID (DID, SPIFFE, or URL). 
  ? identityType: text,       ; Type hint (e.g. "did", "spiffe"). Optional if clear from ID.

  ; --- Metadata ---
  name: text,                 ; Human-readable name
  description: text,          ; Short description
  ? logoUrl: text,            ; Data URL (RFC 2397) recommended
  ? tags: [* text],           ; Discovery keywords
  ? maturity: MaturityLevel,  ; "preview" / "stable" / "deprecated"
  
  ; --- Ownership & Trust ---
  publisher: Publisher,       ; Who owns this agent
  ? trust: Trust,               ; Security, compliance and Identity proofs
  ? signature: text,          ; Detached JWS signing the card content
  
  ; --- Protocols ---
  ; Map of supported protocols (e.g. "a2a" => Service, "mcp" => Service)
  services: { * ServiceType => BaseService }, 

  ; --- Housekeeping ---
  createdAt: tdate,           ; ISO 8601 Date
  updatedAt: tdate,           ; ISO 8601 Date
  ? metadata: { * text => any } ; Extensible metadata bucket
}

MaturityLevel = "preview" / "stable" / "deprecated"
ServiceType = "mcp" / "a2a" / text

; --- Core Components ---

Publisher = {
  id: text,                   ; Verifiable ID of the publisher organization
  ? identityType: text,       ; Type hint (e.g. "did", "dns")
  name: text,
  ? attestation: Attestation  ; Proof of the publisher's identity
}

Trust = {
  ; Identity is now implicit (matches Root ID)
  ? attestations: [* Attestation], ; Compliance proofs (SOC2, HIPAA)
  ? privacyPolicyUrl: text,
  ? termsOfServiceUrl: text
}

Attestation = {
  type: text,                 ; e.g. "SOC2-Type2", "HIPAA-Audit"
  ? credentialUrl: text,      ; Remote JWT/Report (High Trust)
  ? credentialValue: text     ; Embedded JWT (High Trust)
}

; --- Interaction Services ---

BaseService = {
  type: ServiceType,          ; Protocol ID (matches key)
  name: text,                 ; Human-readable label (e.g. "Primary Interface")
  
  ; The "Black Box" for protocol-specific data
  ; Endpoints, Auth, and Skills are defined INSIDE here by the protocol spec.
  protocolSpecific: { * text => any } 
}