machine-readable ai service discovery via standardized metadata schema
Enables AI agents and clients to discover service capabilities by parsing a standardized /.well-known/ai.json manifest file containing provider metadata, capability declarations, transport types, and authentication endpoints. Uses a JSON schema-based approach with optional OpenAPI/JSON Schema integration to describe available operations, resources, and prompts without requiring hardcoded integrations or manual documentation parsing.
Unique: Uses a /.well-known/ convention (borrowed from web standards like ACME, WebFinger) combined with JOSE/JWKS signature verification for tamper-proof capability declarations, enabling cryptographically-verified service metadata without requiring a centralized registry. Provides optional mapping tables to both MCP and agents.json formats, allowing a single manifest to serve multiple agent framework ecosystems.
vs alternatives: Unlike ad-hoc API documentation or proprietary agent integration formats, AI Manifest provides a standardized, cryptographically-verifiable discovery mechanism that reduces friction in agent-to-service integration while leveraging existing OpenAPI/JSON Schema conventions familiar to API developers.
jwks-based cryptographic signature verification for manifest authenticity
Implements JOSE/JWKS (JSON Web Key Set) signature verification allowing agents to validate that an ai.json manifest has not been tampered with by checking RS256 signatures against the provider's public key set at /.well-known/jwks.json. Supports key rotation with a minimum 7-day overlap window using key IDs (kid) to prevent service disruption during key transitions.
Unique: Applies JOSE/JWKS standards (RFC 7517/7518) to AI service discovery, enabling cryptographic verification of capability declarations without requiring a centralized certificate authority. The 7-day key rotation overlap window is explicitly specified to prevent service disruption, a detail often overlooked in other signature schemes.
vs alternatives: Provides stronger authenticity guarantees than unsigned OpenAPI specs or unverified agent registries by leveraging industry-standard JOSE/JWKS cryptography, while remaining simpler than full PKI infrastructure required by traditional certificate-based approaches.
schema-based capability declaration with optional openapi/json schema integration
Allows providers to declare available capabilities (callable operations) using a standardized schema that optionally references OpenAPI specifications or inline JSON Schema definitions. Capabilities are declared as an array of strings or objects with input/output schemas, enabling agents to understand operation signatures without parsing natural language documentation or making exploratory API calls.
Unique: Decouples capability declaration from transport implementation by using JSON Schema as the canonical representation, allowing a single capability definition to be mapped to REST endpoints, MCP tools, or WebSocket operations without duplication. Provides optional mapping tables showing how OpenAPI operations translate to MCP tool definitions.
vs alternatives: Unlike OpenAPI alone (which is REST-centric) or MCP tool definitions (which are agent-specific), AI Manifest's schema-based approach enables transport-agnostic capability declaration that can serve multiple agent frameworks from a single manifest.
multi-transport server declaration with rest/mcp/websocket/sse support
Enables providers to declare multiple server endpoints in a single manifest, specifying transport type (REST, MCP, WebSocket, Server-Sent Events) and URL for each. Agents can select the appropriate transport based on their capabilities, allowing a single service to expose the same logical capabilities through different protocols without requiring separate manifests.
Unique: Treats transport as a deployment detail rather than a capability boundary, allowing providers to declare multiple server implementations in a single manifest. This enables gradual migration from REST to MCP or other protocols without breaking existing integrations or requiring manifest versioning.
vs alternatives: Unlike separate OpenAPI specs for REST and MCP tool definitions, AI Manifest's unified server declaration reduces duplication and makes it explicit that the same logical capabilities are available across multiple transports, improving agent decision-making.
read-only resource and prompt template declaration
Allows providers to declare read-only data resources (e.g., datasets, documents, knowledge bases) and preset prompt templates that agents can reference or retrieve. Resources are declared with URIs and optional schemas, enabling agents to discover and consume provider-hosted data without hardcoding resource URLs or prompt engineering.
Unique: Extends AI Manifest beyond capability declaration to include data and prompt assets, enabling a single manifest to serve as a complete service descriptor for agents. Resources and prompts are optional, allowing providers to start with capability-only manifests and evolve toward richer declarations.
vs alternatives: Unlike separate documentation or hardcoded resource URLs, AI Manifest's resource declaration enables agents to discover and consume provider-hosted data programmatically, reducing integration friction and enabling dynamic resource discovery.
json schema validation cli for manifest compliance checking
Provides Node.js-based command-line validation scripts (validate-ai.mjs, validate-jwks.mjs, validate-crl.mjs) that check ai.json manifests against the AI Manifest schema, verify JWKS endpoint compliance, and validate Certificate Revocation List format. Outputs validation reports to _reports/ directory and integrates with GitHub Actions for CI/CD pipelines.
Unique: Provides reference validation tooling as part of the specification package, reducing friction for early adopters. Includes GitHub Actions workflow template, enabling zero-configuration CI/CD integration for manifest validation.
vs alternatives: Unlike generic JSON Schema validators, the AI Manifest CLI provides domain-specific validation for JWKS and CRL formats, and includes CI/CD templates that reduce setup time for teams adopting the standard.
wellknownai public registry with optional mirroring support
Maintains a public registry (WellKnownAI at wellknownai.org) where providers can list their ai.json manifests by submitting pull requests to a registry.json file. Supports optional mirroring of manifests without PII constraints, enabling centralized discovery of AI services while maintaining provider autonomy over manifest hosting.
Unique: Implements a decentralized registry model where providers maintain authoritative manifests on their own infrastructure while optionally listing in a central directory. This avoids the single point of failure of fully centralized registries while providing discovery benefits.
vs alternatives: Unlike proprietary agent marketplaces (e.g., OpenAI Plugin Store) that require approval and centralized hosting, WellKnownAI enables provider autonomy by allowing self-hosted manifests while providing optional centralized discovery.
mcp and agents.json mapping with transport-agnostic capability translation
Provides mapping tables and guidance for translating AI Manifest capability declarations to Model Context Protocol (MCP) tool definitions and agents.json format. Enables a single manifest to serve multiple agent framework ecosystems by defining how capabilities, resources, and prompts map to framework-specific representations (e.g., MCP tools, agents.json actions).
Unique: Acknowledges that different agent frameworks have incompatible capability representations and provides explicit mapping guidance rather than pretending full compatibility. The (~) notation for incomplete mappings is transparent about limitations, helping implementers understand where manual work is required.
vs alternatives: Unlike frameworks that require separate integrations for each agent ecosystem, AI Manifest's mapping approach enables a single manifest to serve multiple frameworks, though with acknowledged limitations that require framework-specific adaptation.
+1 more capabilities