{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://poliergaleio.com/poliergaleio-lifecycle-error.schema.json",
  "title": "PoliErgaleio lifecycle error (410 Gone / 426 Upgrade Required)",
  "description": "Shared error body returned when a tool has been removed after its sunset date (410) or when the caller's X-Client-Version is below minimumClientVersion (426). Both variants carry error, code, tool, status, replacement, migrationGuide and migrationSections so one code path can parse either.",
  "type": "object",
  "required": [
    "error",
    "code",
    "tool",
    "status",
    "replacement",
    "migrationGuide",
    "migrationSections",
    "requestId"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable explanation, safe to show to an end user."
    },
    "code": {
      "type": "string",
      "enum": [
        "tool_gone",
        "upgrade_required"
      ],
      "description": "Machine-readable discriminator: tool_gone => HTTP 410, upgrade_required => HTTP 426."
    },
    "tool": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tool the request targeted, or null when the request path names no tool."
    },
    "status": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "stable",
        "beta",
        "deprecated",
        "removed",
        null
      ],
      "description": "Lifecycle status of the named tool at the time of the request."
    },
    "replacement": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tool to call instead, or null when there is no direct replacement."
    },
    "sunset": {
      "type": "string",
      "format": "date",
      "description": "RFC 8594 sunset date on which the tool was removed (410 only)."
    },
    "notes": {
      "type": "string",
      "description": "Extra guidance, usually a migration guide URL."
    },
    "migrationGuide": {
      "type": "string",
      "format": "uri",
      "description": "Exact https://poliergaleio.com/migrations/v<x-y-z> page to follow."
    },
    "migrationSections": {
      "type": "object",
      "required": [
        "whatChanged",
        "toolChanges",
        "updateSteps"
      ],
      "additionalProperties": false,
      "properties": {
        "whatChanged": {
          "type": "string",
          "format": "uri"
        },
        "toolChanges": {
          "type": "string",
          "format": "uri"
        },
        "updateSteps": {
          "type": "string",
          "format": "uri"
        }
      },
      "description": "Deep links into the migration guide's three sections."
    },
    "migrationPath": {
      "type": "array",
      "description": "426 only: every guide between the caller's version and the current API version, oldest first.",
      "items": {
        "type": "object",
        "required": [
          "version",
          "url"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "summary": {
            "type": "string"
          },
          "sections": {
            "type": "object"
          }
        }
      }
    },
    "latestMigrationGuide": {
      "type": "string",
      "format": "uri",
      "description": "426 only: newest guide URL."
    },
    "migrationNotes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "426 only: ordered upgrade hints."
    },
    "clientVersion": {
      "type": "string",
      "description": "426 only: version the caller sent in X-Client-Version."
    },
    "minimumClientVersion": {
      "type": "string",
      "description": "426 only: oldest client build still accepted."
    },
    "apiVersion": {
      "type": "string",
      "description": "Current API version."
    },
    "updateUrl": {
      "type": "string",
      "format": "uri",
      "description": "426 only: where to get an updated client."
    },
    "availableTools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "410 only: every tool currently callable."
    },
    "hint": {
      "type": "string",
      "description": "One actionable next step an agent can follow verbatim."
    },
    "requestId": {
      "type": "string",
      "description": "Correlation id, mirrored in the X-Request-Id header."
    },
    "guestId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Opaque x-guest-id you sent, or null."
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "code": {
            "const": "tool_gone"
          }
        },
        "required": [
          "code"
        ]
      },
      "then": {
        "required": [
          "sunset",
          "availableTools"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "code": {
            "const": "upgrade_required"
          }
        },
        "required": [
          "code"
        ]
      },
      "then": {
        "required": [
          "clientVersion",
          "minimumClientVersion",
          "migrationPath"
        ]
      }
    }
  ],
  "examples": [
    {
      "error": "Tool old_tool was removed on 2026-01-01 and is no longer available.",
      "code": "tool_gone",
      "tool": "old_tool",
      "status": "removed",
      "sunset": "2026-01-01",
      "replacement": "new_tool",
      "notes": "See https://poliergaleio.com/migrations/v1-8-0",
      "migrationGuide": "https://poliergaleio.com/migrations/v1-8-0",
      "migrationSections": {
        "whatChanged": "https://poliergaleio.com/migrations/v1-8-0#what-changed",
        "toolChanges": "https://poliergaleio.com/migrations/v1-8-0#tool-changes",
        "updateSteps": "https://poliergaleio.com/migrations/v1-8-0#update-steps"
      },
      "availableTools": [
        "calculate_cyprus_income_tax"
      ],
      "hint": "Call new_tool instead, then follow https://poliergaleio.com/migrations/v1-8-0#update-steps.",
      "requestId": "9f1c0f2e-2f7c-4f0a-9d0e-0a1b2c3d4e5f",
      "guestId": null
    },
    {
      "error": "Client version 0.9.0 is no longer supported. Minimum supported version is 1.0.0.",
      "code": "upgrade_required",
      "tool": "calculate_cyprus_income_tax",
      "status": "stable",
      "replacement": null,
      "clientVersion": "0.9.0",
      "minimumClientVersion": "1.0.0",
      "apiVersion": "1.8.0",
      "updateUrl": "https://poliergaleio.com/developers",
      "migrationGuide": "https://poliergaleio.com/migrations/v1-2-0",
      "migrationSections": {
        "whatChanged": "https://poliergaleio.com/migrations/v1-2-0#what-changed",
        "toolChanges": "https://poliergaleio.com/migrations/v1-2-0#tool-changes",
        "updateSteps": "https://poliergaleio.com/migrations/v1-2-0#update-steps"
      },
      "migrationPath": [
        {
          "version": "1.2.0",
          "url": "https://poliergaleio.com/migrations/v1-2-0",
          "summary": "requestId/guestId everywhere, schema examples, ETag caching",
          "sections": {}
        }
      ],
      "latestMigrationGuide": "https://poliergaleio.com/migrations/v1-8-0",
      "migrationNotes": [
        "Start here: https://poliergaleio.com/migrations/v1-2-0#update-steps"
      ],
      "requestId": "1b2c3d4e-5f60-4718-8a9b-0c1d2e3f4a5b",
      "guestId": null
    }
  ]
}