v1Exception

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/kognitos/main/json-schema/kognitos-v1-exception-schema.json",
  "title": "v1Exception",
  "description": "An exception that occurred during an automation run.\nExceptions are raised by the interpreter and are analogous to Python exceptions.\nHowever, the Kognitos platform provides various mechanisms to resolve an\nexception and then resume the run.\nAutomation runs are important business processes for our users, so the expectation\nis that every exception needs to be resolved even if the resolution involves manual steps\nor abandoning the automation run.",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kognitos-openapi.yml#/components/schemas/v1Exception",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "title": "The full resource name of the exception.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"
    },
    "run": {
      "type": "string",
      "title": "The run in which the exception occurred. The run must belong\nto the same workspace as the exception.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"
    },
    "location": {
      "$ref": "#/$defs/commonV1Location"
    },
    "message": {
      "type": "string",
      "description": "The exception message generated by the interpreter."
    },
    "create_time": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of when the exception was created.",
      "readOnly": true
    },
    "update_time": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of when the exception was last updated.",
      "readOnly": true
    },
    "state": {
      "$ref": "#/$defs/v1ExceptionState"
    },
    "automation": {
      "type": "string",
      "title": "The automation that the exception belongs to. The automation of an exception\nis the automation that the run belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "A human-friendly description of the exception. Generated by the exception service.\nRecently created exceptions may not yet have a description.",
      "readOnly": true
    },
    "group": {
      "type": "string",
      "description": "Groups are used to categorize exceptions\nCurrently support static groups: \"missing_values\", \"user_system_error\", \"internal_error\"\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nIn future, we may support dynamic groups.\nEmpty string means the exception is not grouped."
    },
    "resolution_guide_entry": {
      "type": "string",
      "title": "The guide entry that was used to automatically resolve this exception.\nSet when the exception service successfully applies\na guide entry to resolve the exception i.e exception.state should be RESOLVED if this field is set.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}",
      "readOnly": true
    },
    "stage": {
      "$ref": "#/$defs/v1AutomationStage"
    },
    "execution_id": {
      "type": "string",
      "title": "The execution ID within the run where this exception occurred.\nUsed to differentiate exceptions at the same location with the same message.\nExample: \"exec_123abc\" or a UUID"
    },
    "extra": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Extra information about the exception."
    },
    "assignee": {
      "type": "string",
      "title": "The user assigned to resolve this exception.\nFormat: users/{user}"
    },
    "resolver": {
      "type": "string",
      "description": "The entity that resolved this exception.\nCan be either a user (for manual resolutions) or an agent (for automatic resolutions).\nFormat: users/{user} or agents/{agent}\nNote: No resource_reference is specified to avoid service dependencies and to support\nmultiple resource types in a single field."
    }
  },
  "required": [
    "run",
    "location",
    "message"
  ],
  "$defs": {
    "commonV1Location": {
      "type": "object",
      "properties": {
        "start_byte": {
          "type": "string",
          "format": "int64",
          "title": "Starting Byte of the span, It will be zero-based"
        },
        "end_byte": {
          "type": "string",
          "format": "int64",
          "title": "Ending Byte(exclusive) of the span, It will be zero-based"
        }
      },
      "description": "Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."
    },
    "v1AutomationStage": {
      "type": "string",
      "enum": [
        "AUTOMATION_STAGE_UNSPECIFIED",
        "AUTOMATION_STAGE_DRAFT",
        "AUTOMATION_STAGE_PUBLISHED"
      ],
      "default": "AUTOMATION_STAGE_UNSPECIFIED",
      "description": "AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."
    },
    "v1ExceptionState": {
      "type": "string",
      "enum": [
        "EXCEPTION_STATE_UNSPECIFIED",
        "EXCEPTION_STATE_PENDING",
        "EXCEPTION_STATE_RESOLVED",
        "EXCEPTION_STATE_ARCHIVED"
      ],
      "default": "EXCEPTION_STATE_UNSPECIFIED",
      "description": "The state of an exception.\n\n - EXCEPTION_STATE_UNSPECIFIED: The state is not specified.\n - EXCEPTION_STATE_PENDING: The exception is pending resolution.\nThis is the initial state when an exception is created.\nTransitions:\nOn creation --> PENDING\nPENDING --> RESOLVED: Exception successfully resolved (run can continue)\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\n - EXCEPTION_STATE_RESOLVED: The exception has been resolved.\nRESOLVED is a terminal state. Resolved exceptions are retained for historical records\nTransitions:\nPENDING --> RESOLVED: Exception resolved (run can continue)\n - EXCEPTION_STATE_ARCHIVED: The exception has been archived.\nArchived exceptions are retained for historical records and audit purposes.\nTransitions:\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\nARCHIVED --> PENDING: Exception unarchived (run can continue)"
    }
  }
}