spec: post-meeting converged AI Card profile proposal

specification/cddl/ai-card-metadata.cddl

@@ -0,0 +1,17 @@
+; ==========================================================================
+; SEP-0015 AI Card Metadata Profile CDDL
+; ==========================================================================
+
+Card = {
+  id: text
+  name: text
+  description: text
+  publisher: Publisher
+  ? logoUrl: text
+  ? tags: [ * text ]
+}
+
+Publisher = {
+  id: text
+  name: text
+}

specification/cddl/ai-catalog.cddl

@@ -0,0 +1,39 @@
+; ==========================================================================
+; SEP-0015 AI Catalog Profile CDDL (OCI Image Index)
+; ==========================================================================
+
+Catalog = {
+  schemaVersion: 2
+  mediaType: "application/vnd.oci.image.index.v1+json"
+  artifactType: "application/vnd.aaif.ai.catalog.v1+json"
+  manifests: [* ManifestDescriptor]
+  ? annotations: {
+    * text => text
+  }
+  ? subject: Descriptor
+}
+
+ManifestDescriptor = {
+  mediaType: "application/vnd.oci.image.manifest.v1+json"
+  artifactType: "application/vnd.aaif.ai.manifest.v1+json"
+  digest: text
+  size: uint
+  ? urls: [* text],
+  ? annotations: {
+    "org.aaif.ai.card.id": text
+    "org.aaif.ai.card.specVersion": text
+    * text => text
+  }
+}
+
+Descriptor = {
+  mediaType: text
+  digest: text
+  size: uint
+  ? data: text
+  ? urls: [ * text ]
+  ? annotations: {
+    * text => text
+  }
+  ? artifactType: text
+}

specification/cddl/ai-manifest.cddl

@@ -0,0 +1,39 @@
+; ==========================================================================
+; SEP-0015 AI Manifest Profile CDDL (OCI Image Manifest)
+; ==========================================================================
+
+Manifest = {
+  schemaVersion: 2
+  mediaType: "application/vnd.oci.image.manifest.v1+json"
+  artifactType: "application/vnd.aaif.ai.manifest.v1+json"
+  config: ConfigDescriptor
+  layers: [ * Descriptor ]
+  annotations: {
+    "org.aaif.ai.card.id": text
+    "org.aaif.ai.card.specVersion": text
+    * text => text
+  }
+  ? subject: Descriptor
+}
+
+ConfigDescriptor = {
+  mediaType: "application/vnd.aaif.ai.card.metadata.v1+json"
+  digest: text
+  size: uint
+  ? data: text
+  ? annotations: {
+    * text => text
+  }
+}
+
+Descriptor = {
+  mediaType: text
+  digest: text
+  size: uint
+  ? data: text
+  ? urls: [ * text ]
+  ? annotations: {
+    * text => text
+  }
+  ? artifactType: text
+}

specification/examples/.gitignore

@@ -0,0 +1,2 @@
+# Ignore local OCI example registry
+ai-registry/

specification/examples/README.md

@@ -0,0 +1,223 @@
+# Example Reference Implementation
+
+This document provides a reference implementation of the AI Card specification using a local OCI registry layout and common OCI tooling.
+
+No custom implementations are required - any OCI-compliant registry and tooling should work as long as they support the necessary OCI Distribution Specification (v1.1).
+
+## Requirements
+
+All commands in this example are executed relative to the path of this file.
+
+```bash
+git clone https://github.com/agent-card/ai-card.git
+cd ai-card/specification/examples
+
+# Run the example or execute commands manually
+bash run-example.sh
+```
+
+**Dependencies**
+
+- [jq](https://github.com/jqlang/jq)
+- [cddl](https://github.com/anweiss/cddl)
+- [oras](https://github.com/oras-project/oras)
+- [notation](https://github.com/notaryproject/notation)
+
+## Filesystem Layout
+
+```bash
+$ tree ai-registry
+├── blobs
+│   └── sha256
+│       ├── 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a # Empty blob
+│       ├── 4e8af39bd452bcc0ff38e1d21c6b08dab8abff8b879f36b387cd58de7a238059 # AI Catalog OCI Index
+│       ├── 73ad9bcca5122bbf6cbe7a8f09288462ce9ff009735daf9ced66394ef320c744 # A2A Card Blob
+│       ├── 7ee760e03c7ccf3960a1e4cb78279aad9fb7e4d87f8b6c53729f58215d47e3b4 # MCP Server Blob
+│       ├── 8027cfed688efb48eb4b8304670fb4e5ed0632381a59b28542ed343cb1ce42e8 # AI Manifest with autodiscovery subject
+│       ├── 89762e5233c3954633ff3239a6a4dfe22ef83e5808b00e61446602dd4335ddcc # AI Manifest Blob
+│       ├── ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356 # Empty manifest blob for autodiscovery
+│       ├── fcbfb0c89583232e9c1df732a9d02ca57ddd83fe6ff128ec3e51ea04d4c7ce1e # AI Card Metadata Blob
+│       ├── <signature-blob-hash> # Dynamic, signature blob for AI Manifest
+│       └── <signature-referrer-hash> # Dynamic, signature referrer for AI Manifest
+├── index.json
+├── ingest
+└── oci-layout
+```
+
+## Producer Workflow
+
+This workflow demonstrates how to create and publish AI Manifests and AI Catalogs to an OCI registry, as well as signing for content authenticity and integrity verification.
+
+### Create AI Manifest
+
+```bash
+# Create and push AI Manifest with AI Card config and MCP/A2A layer blobs
+oras push \
+    --oci-layout ai-registry:example-agent \
+    --export-manifest /tmp/manifest.json \
+    --artifact-type application/vnd.aaif.ai.manifest.v1+json \
+    --annotation "org.aaif.ai.card.id=did:example:agent-finance-001" \
+    --annotation "org.aaif.ai.card.specVersion=1.0" \
+    --annotation "org.opencontainers.image.created=2026-03-10T15:00:00Z" \
+    --config ai-card-metadata.json:application/vnd.aaif.ai.card.metadata.v1+json \
+    a2a-card.json:application/vnd.a2a.card.v1+json \
+    mcp-server.json:application/vnd.mcp.card.v1+json
+```
+
+### Sign AI Manifest
+
+```bash
+# Generate sample signing key
+notation cert generate-test --default "ai-manifest.test.io" || echo "already exists"
+
+# Sign using notation
+NOTATION_EXPERIMENTAL=1 notation sign \
+    --oci-layout ai-registry:example-agent
+```
+
+### Create AI Catalog
+
+```bash
+# Create and push AI Catalog with example-agent
+oras manifest index create \
+    --oci-layout ai-registry:catalog \
+    --artifact-type "application/vnd.aaif.ai.catalog.v1+json" \
+    example-agent
+```
+
+## Consumer Workflow
+
+This workflow demonstrates how to discover and retrieve AI Manifests and AI Catalogs from an OCI registry, as well as how to verify AI Manifest signatures.
+
+### List AI Catalog
+
+```bash
+# Get AI Manifests using AI Catalog
+oras manifest fetch \
+    --oci-layout ai-registry:catalog \
+    --format go-template --template '{{ toPrettyJson .content }}'
+```
+
+### Get A2A/MCP Data
+
+```bash
+# Get protocol blob data from AI Manifest
+for MEDIA_TYPE in "application/vnd.a2a.card.v1+json" "application/vnd.mcp.card.v1+json"; do
+  BLOB_DIGEST=$(oras pull --no-tty \
+      --oci-layout ai-registry:example-agent \
+      --format go-template \
+      --template "{{ range .files }}{{ if eq .mediaType \"$MEDIA_TYPE\" }}{{ .digest }}{{ end }}{{ end }}" \
+  )
+
+  echo "=== $MEDIA_TYPE ==="
+  oras blob fetch --no-tty \
+      --oci-layout "ai-registry@$BLOB_DIGEST" \
+      --output -
+done
+```
+
+### List AI Manifest OCI Referrers
+
+```bash
+# Show all links to OCI Manifest (e.g. signatures, metrics, etc)
+oras discover \
+    --oci-layout ai-registry:example-agent \
+    --format json
+```
+
+### Verify AI Manifest Signature
+
+```bash
+# Create trust policy
+cat <<EOF > /tmp/trustpolicy.json
+{
+    "version": "1.0",
+    "trustPolicies": [
+        {
+            "name": "ai-registry-policy",
+            "registryScopes": [ "local/ai-registry" ],
+            "signatureVerification": {
+                "level" : "strict"
+            },
+            "trustStores": [ "ca:ai-manifest.test.io" ],
+            "trustedIdentities": [
+                "*"
+            ]
+        }
+    ]
+}
+EOF
+
+# Import policy
+notation policy import /tmp/trustpolicy.json
+
+# Verify using notation
+NOTATION_EXPERIMENTAL=1 notation verify \
+    --oci-layout ai-registry:example-agent \
+    --scope "local/ai-registry"
+```
+
+## Autodiscovery Workflow
+
+This workflow demonstrates how to use a constant subject descriptor in the AI Manifest to enable auto-discovery of AI Manifests via OCI Referrers API without relying on AI Catalog.
+
+```bash
+# Push empty manifest as constant for auto-discovery.
+# The descriptor of this manifest is always the same.
+# Digest: sha256:ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356
+oras manifest push \
+    --oci-layout ai-registry \
+    --media-type application/vnd.oci.image.manifest.v1+json \
+    empty.json
+
+# Add subject to the AI manifest for autodiscovery via OCI Referrers API
+# Use constant manifest to make discovery consistent across APIs.
+cat <<EOF | jq -s '.[1] * .[0]' - /tmp/manifest.json > /tmp/manifest-with-subject.json
+{
+    "subject": {
+        "mediaType": "application/vnd.oci.image.manifest.v1+json",
+        "digest": "sha256:ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356",
+        "size": 3
+    }
+}
+EOF
+
+# Push manifest with subject for auto-discovery.
+oras manifest push \
+    --oci-layout ai-registry \
+    /tmp/manifest-with-subject.json
+
+# Get AI Manifests using constant subject for auto-discovery
+oras discover \
+    --oci-layout ai-registry@sha256:ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356 \
+    --artifact-type "application/vnd.aaif.ai.manifest.v1+json" \
+    --format json
+```
+
+## CDDL Conformance
+
+Validate that the implementation conforms to the specification using the provided CDDL schemas and `cddl` CLI tool.
+
+### AI Card metadata
+
+```bash
+cddl validate --cddl ../cddl/ai-card-metadata.cddl --json ./ai-card-metadata.json
+```
+
+### AI Manifest
+
+```bash
+oras manifest fetch \
+    --oci-layout ai-registry:example-agent \
+    --format go-template --template '{{ toPrettyJson .content }}' \
+    | cddl validate --cddl ../cddl/ai-manifest.cddl --stdin
+```
+
+### AI Catalog
+
+```bash
+oras manifest fetch \
+    --oci-layout ai-registry:catalog \
+    --format go-template --template '{{ toPrettyJson .content }}' \
+    | cddl validate --cddl ../cddl/ai-catalog.cddl --stdin
+```

specification/examples/a2a-card.json

@@ -0,0 +1,36 @@
+{
+  "name": "Acme Finance Agent",
+  "description": "Executes finance workflows through multiple protocol adapters.",
+  "version": "1.0.0",
+  "supportedInterfaces": [
+    {
+      "url": "https://api.acme-finance.com/a2a/v1",
+      "protocolBinding": "JSONRPC",
+      "protocolVersion": "1.0"
+    }
+  ],
+  "provider": {
+    "url": "https://acme-finance.com",
+    "organization": "Acme Financial Corp"
+  },
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": true,
+    "stateTransitionHistory": false
+  },
+  "defaultInputModes": ["application/json", "text/plain"],
+  "defaultOutputModes": ["application/json", "text/plain"],
+  "skills": [
+    {
+      "id": "skill-stock-analysis",
+      "name": "Run Stock Analysis",
+      "description": "Analyzes stock market data and provides investment insights.",
+      "tags": ["finance", "analysis"],
+      "examples": [
+        "Analyze AAPL and TSLA momentum for this week"
+      ],
+      "inputModes": ["application/json", "text/plain"],
+      "outputModes": ["application/json", "text/plain"]
+    }
+  ]
+}

specification/examples/ai-card-metadata.json

@@ -0,0 +1,11 @@
+{
+  "id": "did:example:agent-finance-001",
+  "name": "Acme Finance Agent",
+  "description": "Executes finance workflows through multiple protocol adapters.",
+  "logoUrl": "https://example.com/logo.png",
+  "publisher": {
+    "id": "did:example:org-acme",
+    "name": "Acme Financial Corp"
+  },
+  "tags": ["finance", "accounting", "payroll"]
+}

specification/examples/empty.json

@@ -0,0 +1 @@
+{}

specification/examples/mcp-server.json

@@ -0,0 +1,21 @@
+{
+  "protocolVersion": "2025-03-26",
+  "serverInfo": {
+    "name": "Acme MCP Server",
+    "version": "1.0.0"
+  },
+  "capabilities": {
+    "logging": {},
+    "prompts": {
+      "listChanged": true
+    },
+    "resources": {
+      "subscribe": true,
+      "listChanged": true
+    },
+    "tools": {
+      "listChanged": true
+    }
+  },
+  "instructions": "Use tools for finance workflows and resources for market context."
+}