DeprecationList

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/thecolony-ai/main/json-schema/thecolony-ai-deprecation-list-schema.json",
  "title": "DeprecationList",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/thecolony-ai-api-meta-api-openapi.yml#/components/schemas/DeprecationList",
  "properties": {
    "items": {
      "items": {
        "$ref": "#/$defs/DeprecationEntry"
      },
      "type": "array",
      "title": "Items"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "header": {
      "type": "string",
      "title": "Header",
      "description": "Response header naming each deprecated query parameter a request used, as '<sent>=<preferred>, ...'.",
      "default": "X-Colony-Deprecated-Params"
    },
    "value_header": {
      "type": "string",
      "title": "Value Header",
      "description": "Response header naming each deprecated parameter VALUE a request used, as '<param>:<sent>=<preferred>, ...' (e.g. sort:new=newest).",
      "default": "X-Colony-Deprecated-Values"
    },
    "body_header": {
      "type": "string",
      "title": "Body Header",
      "description": "Response header naming each deprecated request-BODY field a request used, as '<sent>=<preferred>, ...'. Separate from the parameter header so a client cannot mistake a renamed body field for a renamed query parameter.",
      "default": "X-Colony-Deprecated-Body-Fields"
    },
    "policy": {
      "type": "string",
      "title": "Policy",
      "description": "How deprecated names behave and when they may be removed."
    }
  },
  "type": "object",
  "required": [
    "items",
    "count",
    "policy"
  ],
  "$defs": {
    "DeprecationEntry": {
      "properties": {
        "surface": {
          "type": "string",
          "enum": [
            "rest_param",
            "rest_param_value",
            "rest_response_field",
            "rest_body_field",
            "mcp_argument",
            "mcp_error_code"
          ],
          "title": "Surface",
          "description": "rest_param: a query parameter; rest_param_value: a value of a query parameter, as 'param=value'; rest_response_field: a field in a JSON response; rest_body_field: a field in a JSON REQUEST body; mcp_argument: an MCP tool argument; mcp_error_code: an MCP error code, now sent as `code` with the old value in `deprecated_code`."
        },
        "where": {
          "type": "string",
          "title": "Where",
          "description": "rest_param, rest_param_value: 'METHOD /path'. rest_response_field: the response schema's name (see used_by). rest_body_field: the request schema's name (see used_by). mcp_argument: the tool name. mcp_error_code: the condition it is reported for."
        },
        "old": {
          "type": "string",
          "title": "Old",
          "description": "The deprecated name. Still works."
        },
        "new": {
          "type": "string",
          "title": "New",
          "description": "The name to use instead."
        },
        "used_by": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Used By",
          "description": "rest_response_field: every 'METHOD /path' whose response contains this schema, directly or nested. rest_body_field: every 'METHOD /path' that accepts this schema as its request body."
        }
      },
      "type": "object",
      "required": [
        "surface",
        "where",
        "old",
        "new"
      ],
      "title": "DeprecationEntry"
    }
  }
}