Agent Readiness · Schema

AgentReadinessSignal

A single observable signal that an API provider supports a specific dimension of agent readiness, with an evidence URL that anchors the score.

Agent ReadinessAI AgentsAPI DiscoveryAPI GovernanceMachine-Readable APIsMCPOpenAPIAsyncAPI

Properties

Name	Type	Description
id	string	Stable identifier for the signal, typically `{providerSlug}-{dimensionSlug}`.
provider	string	Canonical name of the API provider this signal describes.
providerSlug	string	Lowercased, hyphenated slug used for cross-references.
dimension	string	The agent-readiness dimension being scored. See vocabulary/agent-readiness-vocabulary.yaml for the canonical list.
score	integer	Score from 0 (absent) to 3 (best-in-class). 0=absent, 1=partial/undocumented, 2=present and documented, 3=present, documented, and machine-discoverable.
scoreLabel	string	Human-readable label corresponding to the numeric score.
evidenceUrl	string	Public URL that anchors the score. The page or file an auditor can read to verify the claim.
evidenceQuote	string	Optional verbatim quote from the evidence URL supporting the score.
notes	string	Free-form notes from the reviewer, e.g. caveats or version applicability.
observedOn	string	Date the signal was observed.
observer	string	Person or organisation that recorded the signal.
tags	array	Free-form tags for filtering and grouping signals.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/agent-readiness/refs/heads/main/json-schema/agent-readiness-signal-schema.json",
  "title": "AgentReadinessSignal",
  "description": "A single observable signal that an API provider supports a specific dimension of agent readiness, with an evidence URL that anchors the score.",
  "type": "object",
  "required": ["provider", "dimension", "score", "evidenceUrl", "observedOn"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Stable identifier for the signal, typically `{providerSlug}-{dimensionSlug}`.",
      "example": "stripe-openapi-spec-present"
    },
    "provider": {
      "type": "string",
      "description": "Canonical name of the API provider this signal describes.",
      "example": "Stripe"
    },
    "providerSlug": {
      "type": "string",
      "description": "Lowercased, hyphenated slug used for cross-references.",
      "example": "stripe"
    },
    "dimension": {
      "type": "string",
      "description": "The agent-readiness dimension being scored. See vocabulary/agent-readiness-vocabulary.yaml for the canonical list.",
      "enum": [
        "spec-presence",
        "auth-model-clarity",
        "idempotency",
        "error-semantics",
        "rate-limit-headers",
        "dry-run-mode",
        "openapi-examples",
        "mcp-server",
        "asyncapi-events",
        "well-known-catalog",
        "consent-signals",
        "bot-auth"
      ],
      "example": "spec-presence"
    },
    "score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3,
      "description": "Score from 0 (absent) to 3 (best-in-class). 0=absent, 1=partial/undocumented, 2=present and documented, 3=present, documented, and machine-discoverable.",
      "example": 3
    },
    "scoreLabel": {
      "type": "string",
      "enum": ["absent", "partial", "present", "exemplary"],
      "description": "Human-readable label corresponding to the numeric score.",
      "example": "exemplary"
    },
    "evidenceUrl": {
      "type": "string",
      "format": "uri",
      "description": "Public URL that anchors the score. The page or file an auditor can read to verify the claim.",
      "example": "https://github.com/stripe/openapi"
    },
    "evidenceQuote": {
      "type": "string",
      "description": "Optional verbatim quote from the evidence URL supporting the score.",
      "example": "This repository contains OpenAPI specifications for Stripe's API."
    },
    "notes": {
      "type": "string",
      "description": "Free-form notes from the reviewer, e.g. caveats or version applicability.",
      "example": "Spec is split into preview and stable; both are kept in sync with the changelog."
    },
    "observedOn": {
      "type": "string",
      "format": "date",
      "description": "Date the signal was observed.",
      "example": "2026-05-22"
    },
    "observer": {
      "type": "string",
      "description": "Person or organisation that recorded the signal.",
      "example": "API Evangelist"
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Free-form tags for filtering and grouping signals.",
      "example": ["payments", "rest", "openapi"]
    }
  }
}