SdkVerificationRun

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gunspec-io/json-schema/gunspec-io-sdk-verification-run-schema.json",
  "title": "SdkVerificationRun",
  "description": "One run over every documented example of one surface in one language. Produced in CI by `scripts/verify-sdk-examples.mjs` (the published SDKs), `scripts/verify-api-examples.mjs` (the reference's cURL, TypeScript and Python samples, each executed in the runtime a reader would paste it into) `scripts/verify-engine-samples.mjs` (the game-engine tabs, which are checked rather than executed) or `gunspec-mcp/scripts/verify-tools.mjs` (every tool on the hosted MCP server, called over the protocol).",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gunspec-io-openapi.json#/components/schemas/SdkVerificationRun",
  "type": "object",
  "properties": {
    "surface": {
      "type": "string",
      "enum": [
        "sdk",
        "api",
        "mcp"
      ],
      "description": "Which promise the run is about: `sdk` for the published packages, `api` for the cURL commands the reference prints."
    },
    "language": {
      "type": "string",
      "enum": [
        "typescript",
        "javascript",
        "python",
        "curl",
        "unity",
        "unreal",
        "godot",
        "mcp"
      ],
      "description": "The sample's own language. On an SDK run, `typescript` or `python` for the published package. On an API run, the tab of the reference it came from: `curl`, `javascript` (the TypeScript tab's generated `fetch`), `python` (its generated `requests`), or `unity`, `unreal` and `godot`, which are checked rather than executed."
    },
    "checkKind": {
      "type": "string",
      "enum": [
        "executed",
        "static"
      ],
      "description": "How the run arrived at its results. `executed` ran the sample against this API. `static` could not, and checked the sample against the operation it documents instead: the Unity, Unreal and GDScript samples are fragments meant for a class, an actor or a scene, so running one would mean wrapping it in code the reference does not print."
    },
    "sdkVersion": {
      "type": "string",
      "description": "What was exercised: the release installed from the registry on an SDK run, and the spec version the samples were generated from on an API run. The release rather than the version in our tree, because the badge vouches for what a reader gets today."
    },
    "apiHost": {
      "type": "string",
      "description": "The API the run was executed against. Production, so the badge vouches for the live service rather than a preview."
    },
    "ranAt": {
      "type": "string",
      "description": "When the run finished, ISO 8601."
    },
    "commitSha": {
      "type": [
        "string",
        "null"
      ],
      "description": "The commit of this repository the run was started from, or null where CI did not report one."
    },
    "runUrl": {
      "type": [
        "string",
        "null"
      ],
      "description": "The CI run, so the claim can be checked rather than taken."
    },
    "passed": {
      "type": "integer",
      "description": "Examples that ran and returned what the page prints."
    },
    "failed": {
      "type": "integer",
      "description": "Examples that ran and did not. A non-zero count is what takes the badge down."
    },
    "skipped": {
      "type": "integer",
      "description": "Write examples, which are never run against production: each would create a real ticket, webhook endpoint or seller offer."
    },
    "unsupported": {
      "type": "integer",
      "description": "Examples this SDK has no method for. The reference shows no sample for them either."
    }
  },
  "required": [
    "surface",
    "language",
    "sdkVersion",
    "apiHost",
    "ranAt",
    "passed",
    "failed",
    "skipped",
    "unsupported",
    "examples"
  ]
}