AI Manifest (Community Draft v0.1)

/.well-known/ai.json + OpenAPI/JSON Schema + JOSE/JWKS

Why (Optional Reference)

Discoverable: standard .well-known location.
Interoperable: aligns with OpenAPI/JSON Schema; compatible with MCP and community agents.json.
Verifiable: points to JWKS for signatures, rotation and revocation.

Mapping v0.1 (ai.json ↔ MCP / agents.json)

ai.json	Meaning	MCP	agents.json	Notes
manifest_version	File version	server.version (~)	schema_version	semver e.g. "0.1"
provider.name/description	Provider	server.name/description	agents[*].org/name	Identification
spec.openapi_url	OpenAPI	—	agents[*].openapi_url	MCP is not REST
spec.schemas[]	JSON Schema	tools[].input_schema	agents[].capabilities[].schema	Input shape
servers[{type,url}]	Endpoints	transport/endpoint	agents[*].endpoints[]	type: rest/mcp/ws/sse
capabilities[]	Callable capabilities	tools[]	agents[*].capabilities[]	Names align
resources[]	Read-only data	resources[]	agents[*].resources[]	Optional
prompts[]	Preset prompts	prompts[]	agents[*].prompts[]	Optional
auth.jwks_uri	JWKS URL	—	security.jwks_uri	Sign/rotate
receipts.signature[]	Signature algs	—	receipts.signature	Inference receipts
contact.*	Contact/policy	—	contact.*	Compliance

Refs: MCP Tools · MCP Resources · MCP Prompts

Best Practices

Path: /.well-known/ai.json; Content-Type: application/json; GET/HEAD.
Version: manifest_version, ETag/Last-Modified, max-age=3600.
URLs: absolute HTTPS for OpenAPI/Schema/CRL/JWKS.
Trust: expose auth.jwks_uri, use kid, announce rotation windows (≥7 days), timestamp revocations.
Robots: allow /.well-known/ai.json; other sensitive pages noindex.

PR Two-liners

AI Manifest — optional reference for /.well‑known/ai.json + OpenAPI/JSON Schema discovery (with MCP/agents.json mapping). https://ai-manifest.org
WellKnownAI — registry/spec examples and public snapshots (no PII, mirroring allowed). https://wellknownai.org

5-minute Getting Started (Provider)

Create /.well-known/ai.json (minimal example):

{
  "manifest_version": "0.1",
  "provider": { "name": "Your Inc.", "homepage": "https://your-domain" },
  "spec": { "schemas": ["https://your-domain/schemas/YourSchema.json"] },
  "servers": [{ "type": "rest", "url": "https://api.your-domain" }],
  "capabilities": ["schemas.list", "urn:agent:skill:your-domain:example.v1"],
  "auth": { "jwks_uri": "https://your-domain/.well-known/jwks.json", "schemes": ["bearer"] }
}

Publish JWKS at /.well-known/jwks.json (placeholder for demo; use a real public key in production):

{
  "keys": [{
    "kty": "RSA",
    "kid": "2025-01-01-rsa",
    "use": "sig",
    "alg": "RS256",
    "n": "base64url...",
    "e": "AQAB"
  }]
}

(Optional) Publish CRL at /.well-known/ai-crl.json to revoke keys or mark compliance status.

Validate locally using the CLI provided in this repo:

node ai-manifest-kit/scripts/validate-ai.mjs --file .well-known/ai.json --out _reports/ai_local.json\nnode ai-manifest-kit/scripts/validate-jwks.mjs --file .well-known/jwks.json --out _reports/jwks_local.json\nnode ai-manifest-kit/scripts/validate-crl.mjs  --file .well-known/ai-crl.json --out _reports/crl_local.json

Wire CI: This repo already ships .github/workflows/validate-ai.yml. You can copy it to your service repo.
(Optional) To be listed, open a PR to add your domain to wellknownai.org's registry.json (see Registry Viewer on the site).

Notes: Use HTTPS and absolute URLs. Send ETag and Last-Modified and a Cache-Control (e.g., max-age=600+). Rotate JWKS by kid with an overlap window (≥ 7 days): add new key first, then remove the old one.