schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/aevum-network/agentcard-spec/schema.json",
  "title": "AgentCard",
  "description": "AgentCard v1.0 — the self-declaration of an agent's identity, capabilities, and terms. Pure data schema, zero execution logic. AgentCard is to A2A what HTTP headers are to the web.",
  "type": "object",
  "required": ["agent_id", "name", "version", "capabilities", "endpoint"],
  "additionalProperties": false,
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Globally unique agent identifier. 128-bit ULID encoded as Crockford Base32 (26 characters, characters 0-9 and A-HJKMNP-TV-Z).",
      "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
      "examples": ["01HZQK3P8EMXR9V7T5N2W4J6C0"]
    },
    "name": {
      "type": "string",
      "description": "Human-readable display name of this agent.",
      "minLength": 1,
      "maxLength": 128,
      "examples": ["Mistral-7B Language Agent"]
    },
    "version": {
      "type": "string",
      "description": "Semantic version of this agent's card format (semver 2.0).",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
      "examples": ["1.0.0", "0.3.2-beta.1"]
    },
    "capabilities": {
      "type": "array",
      "description": "List of capabilities this agent offers. At least one capability is required.",
      "minItems": 1,
      "items": { "$ref": "#/$defs/Capability" }
    },
    "endpoint": {
      "$ref": "#/$defs/Endpoint",
      "description": "How to reach this agent."
    },
    "pricing": {
      "oneOf": [
        { "$ref": "#/$defs/PricingModel" },
        { "type": "null" }
      ],
      "description": "Optional cost model for interacting with this agent."
    },
    "metadata": {
      "$ref": "#/$defs/Metadata",
      "description": "Interaction statistics derived from PACR causal history (π projection). These fields are computed from the ledger, not self-declared."
    }
  },
  "$defs": {
    "Capability": {
      "title": "Capability",
      "description": "A single capability that the agent can perform.",
      "type": "object",
      "required": ["id", "description"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Machine-readable capability identifier. Dot-namespaced recommended: domain.verb",
          "pattern": "^[a-z0-9][a-z0-9._-]*$",
          "maxLength": 128,
          "examples": ["text.generate", "code.review", "data.transform"]
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of what this capability does.",
          "minLength": 1,
          "maxLength": 512
        },
        "tags": {
          "type": "array",
          "description": "Optional semantic tags for discovery and routing.",
          "items": {
            "type": "string",
            "maxLength": 64
          },
          "uniqueItems": true
        },
        "input_schema": {
          "description": "JSON Schema describing the input this capability accepts. Null means the input is unstructured.",
          "oneOf": [
            { "type": "object" },
            { "type": "null" }
          ]
        },
        "output_schema": {
          "description": "JSON Schema describing the output this capability produces. Null means the output is unstructured.",
          "oneOf": [
            { "type": "object" },
            { "type": "null" }
          ]
        }
      }
    },
    "Endpoint": {
      "title": "Endpoint",
      "description": "How to reach this agent.",
      "type": "object",
      "required": ["protocol", "url"],
      "additionalProperties": false,
      "properties": {
        "protocol": {
          "$ref": "#/$defs/Protocol"
        },
        "url": {
          "type": "string",
          "description": "URL or address of the endpoint.",
          "format": "uri",
          "examples": ["https://agent.example.com/api", "wss://stream.example.com/events"]
        },
        "health_url": {
          "type": "string",
          "description": "Optional health-check endpoint.",
          "format": "uri"
        },
        "auth": {
          "description": "Authentication configuration. Null means no authentication required.",
          "oneOf": [
            { "$ref": "#/$defs/AuthConfig" },
            { "type": "null" }
          ]
        }
      }
    },
    "Protocol": {
      "title": "Protocol",
      "description": "Transport protocol used to communicate with the agent.",
      "type": "string",
      "enum": ["http", "websocket", "sse", "grpc", "mcp", "google_a2a", "native"],
      "examples": ["http"]
    },
    "AuthConfig": {
      "title": "AuthConfig",
      "description": "Authentication configuration for reaching this agent.",
      "type": "object",
      "required": ["scheme"],
      "additionalProperties": true,
      "properties": {
        "scheme": {
          "type": "string",
          "description": "Authentication scheme name.",
          "enum": ["none", "bearer", "api_key", "oauth2", "mtls"],
          "examples": ["bearer"]
        },
        "token_url": {
          "type": "string",
          "description": "Token endpoint URL (for oauth2 scheme).",
          "format": "uri"
        },
        "header": {
          "type": "string",
          "description": "Header name where the credential is sent (for api_key scheme).",
          "examples": ["X-API-Key"]
        }
      }
    },
    "PricingModel": {
      "title": "PricingModel",
      "description": "Cost model for interacting with this agent. Thermodynamic settlement is in Joules; fiat settlement is optional.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "base_cost_joules": {
          "type": ["number", "null"],
          "description": "Base cost per request in Joules (Landauer thermodynamic unit). This is the canonical unit of account for agent-to-agent settlement. Must be >= 2.854e-21 (Landauer floor at 300K).",
          "minimum": 0,
          "examples": [2.854e-21, 1.0e-18]
        },
        "estimated_latency_ms": {
          "type": ["number", "null"],
          "description": "Estimated end-to-end latency in milliseconds. Derived from PACR Omega (Ω) history when populated via π projection.",
          "minimum": 0,
          "examples": [120.0, 30.5]
        },
        "currency": {
          "type": ["string", "null"],
          "description": "ISO 4217 currency code or token symbol for fiat/token settlement (optional complement to Joule pricing).",
          "pattern": "^[A-Z]{3,10}$",
          "examples": ["USD", "USDC"]
        },
        "cost_per_request": {
          "type": ["number", "null"],
          "description": "Cost per request in the specified fiat/token currency. Only meaningful when 'currency' is also set.",
          "minimum": 0,
          "examples": [0.001]
        }
      }
    },
    "Metadata": {
      "title": "Metadata",
      "description": "Metadata derived from PACR causal history via the π projection function. All fields with prefix 'pacr:' are computed from the causal ledger, not self-declared. Custom fields without the 'pacr:' prefix may be set by the agent operator.",
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "pacr:interaction_count": {
          "type": "integer",
          "description": "Count of PACR records involving this agent_id.",
          "minimum": 0
        },
        "pacr:avg_latency_ms": {
          "type": "number",
          "description": "Time-decay-weighted average latency in milliseconds: Σ(Ω.time × exp(-λΔt)) / Σ(exp(-λΔt)).",
          "minimum": 0
        },
        "pacr:avg_cost_joules": {
          "type": "number",
          "description": "Time-decay-weighted average energy cost in Joules: Σ(Ω.energy × exp(-λΔt)) / Σ(exp(-λΔt)).",
          "minimum": 0
        },
        "pacr:reputation_score": {
          "type": "number",
          "description": "Reputation score in [0.0, 1.0]: f(success_rate, latency, Sτ/Hτ ratio). Higher is better.",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "pacr:influence_rank": {
          "type": "number",
          "description": "PageRank variant on causal interaction graph. Measures how central this agent is to overall system flow.",
          "minimum": 0.0
        },
        "pacr:critical_score": {
          "type": "number",
          "description": "Betweenness centrality score. Higher means more other agents depend on routing through this agent.",
          "minimum": 0.0
        }
      }
    }
  }
}