CapabilityContract

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beatapi/json-schema/beatapi-capability-contract-schema.json",
  "title": "CapabilityContract",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beatapi-openapi.json#/components/schemas/CapabilityContract",
  "type": "object",
  "required": [
    "reference",
    "kind",
    "id",
    "version",
    "status",
    "title",
    "description",
    "execution",
    "versions",
    "validation"
  ],
  "properties": {
    "reference": {
      "type": "string",
      "description": "Stable reference, `kind:id`. Copy it exactly into Inspect and Run."
    },
    "kind": {
      "type": "string",
      "enum": [
        "model",
        "data",
        "workflow"
      ]
    },
    "id": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "readiness": {
      "type": "string",
      "enum": [
        "ready",
        "runnable",
        "listed"
      ],
      "description": "`ready`: runnable, output schema and price published. `runnable`: runs through Run and the input is documented, but the output shape is not published. `listed`: not runnable through Run, or the input is undocumented."
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "entities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Words callers use for this capability; searchable."
    },
    "input_schema": {
      "type": "object",
      "additionalProperties": true,
      "description": "JSON Schema of Run `input`."
    },
    "output_schema": {
      "type": "object",
      "additionalProperties": true,
      "description": "JSON Schema of the result",
      "when published.": null
    },
    "schema_hash": {
      "type": "string",
      "description": "Sixteen hex characters fingerprinting `input_schema` and `output_schema` together. Cache a contract by it and re-inspect only when a later reply shows a different hash."
    },
    "pricing": {
      "type": "object",
      "additionalProperties": true,
      "description": "Current retail price of one run."
    },
    "pagination": {
      "type": "object",
      "additionalProperties": true
    },
    "limits": {
      "type": "object",
      "additionalProperties": true
    },
    "errors": {
      "type": "object",
      "additionalProperties": true
    },
    "documentation": {
      "type": "object",
      "required": [
        "url"
      ],
      "description": "First-party usage guidance. Detailed Run examples appear here for selected data capabilities and are omitted from Search responses.",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "run_example": {
          "type": "object",
          "additionalProperties": true
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "execution": {
      "type": "object",
      "required": [
        "mode",
        "status_supported"
      ],
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "sync",
            "async"
          ],
          "description": "`sync` returns the result from Run; `async` returns a task to poll with operation status."
        },
        "status_supported": {
          "type": "boolean"
        },
        "result_location": {
          "type": "string"
        }
      }
    },
    "versions": {
      "type": "object",
      "required": [
        "catalog_version",
        "contract_version"
      ],
      "properties": {
        "catalog_version": {
          "type": "string"
        },
        "contract_version": {
          "type": "string"
        },
        "price_version": {
          "type": "string"
        }
      }
    },
    "validation": {
      "type": "object",
      "required": [
        "state"
      ],
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "verified",
            "partial",
            "unknown"
          ]
        },
        "verified_at": {
          "type": "string"
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}