{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Common result envelope",
  "description": "Every tool result and every /v1 REST response body is this envelope: a success carrying ok, data, and meta, or a failure carrying ok, error, and meta. meta always states provenance (sources), governance (public_use), and versioning, so an autonomous agent never has to guess what it may do with a value.",
  "$comment": "Self-contained by design: the in-repo validator resolves only document-internal $refs, so #/$defs/error mirrors schemas/common/error-result.schema.json and #/$defs/redistribution mirrors schemas/common/redistribution.schema.json. Tests keep the copies in step.",
  "oneOf": [
    {
      "$ref": "#/$defs/successResult"
    },
    {
      "$ref": "#/$defs/errorResult"
    }
  ],
  "$defs": {
    "successResult": {
      "type": "object",
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false,
      "properties": {
        "ok": {
          "const": true
        },
        "data": {
          "description": "Operation-specific payload. Each tool's result data is specified by its own increment; the envelope constrains only the wrapper."
        },
        "meta": {
          "$ref": "#/$defs/meta"
        }
      }
    },
    "errorResult": {
      "type": "object",
      "required": [
        "ok",
        "error",
        "meta"
      ],
      "additionalProperties": false,
      "properties": {
        "ok": {
          "const": false
        },
        "error": {
          "$ref": "#/$defs/error"
        },
        "meta": {
          "$ref": "#/$defs/meta"
        }
      }
    },
    "meta": {
      "type": "object",
      "required": [
        "request_id",
        "schema_version",
        "data_version",
        "generated_at",
        "warnings",
        "public_use",
        "sources"
      ],
      "additionalProperties": false,
      "properties": {
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Server-assigned identifier of this request, for support and audit."
        },
        "schema_version": {
          "type": "string",
          "minLength": 1,
          "description": "Version of the contract schemas this response conforms to."
        },
        "data_version": {
          "type": "string",
          "minLength": 1,
          "description": "Version of the data edition the response was served from."
        },
        "generated_at": {
          "type": "string",
          "minLength": 1,
          "format": "date-time",
          "description": "RFC 3339 timestamp at which the response was generated."
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque cursor for the next page, or null when this page is the last. Absent when the operation does not paginate."
        },
        "warnings": {
          "type": "array",
          "description": "Non-fatal notices about this response.",
          "items": {
            "type": "string"
          }
        },
        "public_use": {
          "$ref": "#/$defs/redistribution",
          "description": "Response-wide public-use terms, in the same shape as the per-value redistribution object."
        },
        "payment": {
          "$ref": "#/$defs/payment",
          "description": "Present only on paid operations that settled a payment for this response."
        },
        "sources": {
          "type": "array",
          "description": "Every source that contributed to this response.",
          "items": {
            "$ref": "#/$defs/source"
          }
        }
      }
    },
    "payment": {
      "type": "object",
      "description": "x402 settlement summary for the payment that unlocked this response.",
      "required": [
        "price_id",
        "amount"
      ],
      "additionalProperties": false,
      "properties": {
        "price_id": {
          "type": "string",
          "minLength": 1,
          "description": "The immutable price identifier that was charged, e.g. price.search.v1."
        },
        "amount": {
          "type": "string",
          "minLength": 1,
          "description": "Amount settled, as a base-10 string in atomic units."
        },
        "asset": {
          "type": "string",
          "description": "Asset the amount is denominated in."
        },
        "network": {
          "type": "string",
          "description": "Settlement network."
        },
        "receipt": {
          "type": "string",
          "description": "Opaque settlement receipt reference."
        }
      }
    },
    "source": {
      "type": "object",
      "description": "One contributing source. At minimum it names the source and its licence; the optional fields locate and date the contribution.",
      "required": [
        "source_id",
        "licence_id"
      ],
      "additionalProperties": false,
      "properties": {
        "source_id": {
          "type": "string",
          "minLength": 1,
          "description": "Source identifier from the public-data eligibility inventory."
        },
        "licence_id": {
          "type": "string",
          "minLength": 1,
          "description": "Licence identifier the source's data is used under."
        },
        "name": {
          "type": "string",
          "description": "Human-readable source name."
        },
        "url": {
          "type": "string",
          "description": "Where the source publishes the data."
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 timestamp at which the source data was retrieved."
        }
      }
    },
    "error": {
      "$comment": "Mirror of schemas/common/error-result.schema.json; a test keeps the copies in step.",
      "type": "object",
      "required": [
        "code",
        "message",
        "retryable"
      ],
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable explanation of this occurrence of the error."
        },
        "retryable": {
          "type": "boolean",
          "description": "Whether retrying the identical request can succeed without the caller changing anything."
        },
        "invalid_fields": {
          "type": "array",
          "description": "Present on validation failures: the request fields that failed, so an agent can repair the call.",
          "items": {
            "type": "object",
            "required": [
              "field"
            ],
            "additionalProperties": false,
            "properties": {
              "field": {
                "type": "string",
                "minLength": 1,
                "description": "RFC 6901 JSON pointer into the request input."
              },
              "reason": {
                "type": "string",
                "description": "Why the field was rejected."
              }
            }
          }
        },
        "suggested_action": {
          "type": "string",
          "description": "What the caller should do next, phrased for an autonomous agent."
        }
      }
    },
    "redistribution": {
      "$comment": "Mirror of schemas/common/redistribution.schema.json; a test keeps the copies in step.",
      "type": "object",
      "required": [
        "allowed",
        "basis",
        "attribution_required",
        "restrictions"
      ],
      "additionalProperties": false,
      "properties": {
        "allowed": {
          "type": "boolean",
          "description": "Whether the caller may redistribute this value at all."
        },
        "basis": {
          "type": "string",
          "minLength": 1,
          "description": "Licence identifier or eligibility-policy basis grounding the decision, matching a licence_id in meta.sources where one applies."
        },
        "attribution_required": {
          "type": "boolean",
          "description": "Whether redistribution must reproduce the attribution statement."
        },
        "attribution": {
          "type": "string",
          "description": "Attribution statement to reproduce when attribution_required is true. Ratified attribution text is an open Operator decision (S8); until ratified, served values are explicitly marked placeholders."
        },
        "restrictions": {
          "type": "array",
          "description": "Restriction codes narrowing an otherwise-allowed redistribution. The four codes listed here are the entire permitted vocabulary; no other code is valid.",
          "items": {
            "enum": [
              "no-mailing-list",
              "no-mail-generation",
              "no-derivative-works",
              "no-standalone-redistribution"
            ]
          }
        }
      }
    }
  }
}