{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://rollbar.com/schemas/rollbar/occurrence.json",
  "title": "Rollbar Occurrence",
  "description": "A Rollbar occurrence representing a single instance of an error or message. Occurrences are grouped into items based on fingerprinting.",
  "type": "object",
  "required": ["data"],
  "properties": {
    "id": {
      "type": "integer",
      "description": "The occurrence instance ID."
    },
    "item_id": {
      "type": "integer",
      "description": "The item ID this occurrence is grouped under."
    },
    "timestamp": {
      "type": "integer",
      "description": "Unix timestamp when the occurrence happened."
    },
    "version": {
      "type": "integer",
      "description": "The occurrence data format version."
    },
    "data": {
      "type": "object",
      "description": "The full occurrence data payload.",
      "required": ["environment", "body"],
      "properties": {
        "environment": {
          "type": "string",
          "description": "The environment where the occurrence happened (e.g., production, staging).",
          "maxLength": 255
        },
        "body": {
          "$ref": "#/$defs/OccurrenceBody"
        },
        "level": {
          "type": "string",
          "description": "The severity level of the occurrence.",
          "enum": ["critical", "error", "warning", "info", "debug"]
        },
        "timestamp": {
          "type": "integer",
          "description": "Unix timestamp of when the error occurred."
        },
        "code_version": {
          "type": "string",
          "description": "A string identifying the version of the application code.",
          "maxLength": 40
        },
        "platform": {
          "type": "string",
          "description": "The platform on which the error occurred (e.g., linux, windows, browser)."
        },
        "language": {
          "type": "string",
          "description": "The programming language (e.g., python, javascript, ruby)."
        },
        "framework": {
          "type": "string",
          "description": "The application framework (e.g., django, rails, express)."
        },
        "server": {
          "$ref": "#/$defs/ServerData"
        },
        "request": {
          "$ref": "#/$defs/RequestData"
        },
        "person": {
          "$ref": "#/$defs/PersonData"
        },
        "custom": {
          "type": "object",
          "description": "Custom key-value data included with the occurrence."
        },
        "fingerprint": {
          "type": "string",
          "description": "A custom fingerprint for grouping. If provided, overrides automatic fingerprinting."
        },
        "title": {
          "type": "string",
          "description": "A custom title for the occurrence.",
          "maxLength": 255
        },
        "uuid": {
          "type": "string",
          "description": "A unique identifier for this occurrence, generated by the SDK.",
          "format": "uuid"
        },
        "notifier": {
          "type": "object",
          "description": "Information about the SDK or notifier that sent this occurrence.",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the notifier library."
            },
            "version": {
              "type": "string",
              "description": "The version of the notifier library."
            }
          }
        }
      }
    }
  },
  "$defs": {
    "OccurrenceBody": {
      "type": "object",
      "description": "The body of the occurrence containing the error trace or message.",
      "properties": {
        "trace": {
          "$ref": "#/$defs/Trace"
        },
        "trace_chain": {
          "type": "array",
          "description": "A chain of traces for errors with causes.",
          "items": {
            "$ref": "#/$defs/Trace"
          }
        },
        "message": {
          "type": "object",
          "description": "A message payload (for non-exception reports).",
          "properties": {
            "body": {
              "type": "string",
              "description": "The message text."
            }
          },
          "required": ["body"]
        },
        "crash_report": {
          "type": "object",
          "description": "A crash report payload for mobile/native crashes.",
          "properties": {
            "raw": {
              "type": "string",
              "description": "The raw crash report text."
            }
          },
          "required": ["raw"]
        }
      }
    },
    "Trace": {
      "type": "object",
      "description": "A stack trace with exception information.",
      "required": ["frames", "exception"],
      "properties": {
        "frames": {
          "type": "array",
          "description": "Stack frames ordered from oldest to most recent.",
          "items": {
            "$ref": "#/$defs/Frame"
          }
        },
        "exception": {
          "type": "object",
          "description": "Exception class and message.",
          "properties": {
            "class": {
              "type": "string",
              "description": "The exception class name."
            },
            "message": {
              "type": "string",
              "description": "The exception message."
            },
            "description": {
              "type": "string",
              "description": "Additional exception description."
            }
          },
          "required": ["class"]
        }
      }
    },
    "Frame": {
      "type": "object",
      "description": "A single stack frame.",
      "required": ["filename"],
      "properties": {
        "filename": {
          "type": "string",
          "description": "The source file name."
        },
        "lineno": {
          "type": "integer",
          "description": "The line number in the source file."
        },
        "colno": {
          "type": "integer",
          "description": "The column number in the source file."
        },
        "method": {
          "type": "string",
          "description": "The method or function name."
        },
        "code": {
          "type": "string",
          "description": "The line of source code."
        },
        "context": {
          "type": "object",
          "description": "Surrounding source code context.",
          "properties": {
            "pre": {
              "type": "array",
              "description": "Lines of code before the error line.",
              "items": {
                "type": "string"
              }
            },
            "post": {
              "type": "array",
              "description": "Lines of code after the error line.",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "ServerData": {
      "type": "object",
      "description": "Server environment information.",
      "properties": {
        "host": {
          "type": "string",
          "description": "The server hostname."
        },
        "root": {
          "type": "string",
          "description": "The application root directory path."
        },
        "branch": {
          "type": "string",
          "description": "The source control branch name."
        },
        "code_version": {
          "type": "string",
          "description": "The deployed code version or commit SHA."
        },
        "pid": {
          "type": "integer",
          "description": "The server process ID."
        }
      }
    },
    "RequestData": {
      "type": "object",
      "description": "HTTP request data associated with the occurrence.",
      "properties": {
        "url": {
          "type": "string",
          "description": "The full request URL.",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "description": "The HTTP method.",
          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
        },
        "headers": {
          "type": "object",
          "description": "HTTP request headers."
        },
        "params": {
          "type": "object",
          "description": "Request parameters (query string and/or POST body)."
        },
        "GET": {
          "type": "object",
          "description": "Query string parameters."
        },
        "POST": {
          "type": "object",
          "description": "POST body parameters."
        },
        "body": {
          "type": "string",
          "description": "Raw request body."
        },
        "user_ip": {
          "type": "string",
          "description": "The client IP address.",
          "format": "ipv4"
        }
      }
    },
    "PersonData": {
      "type": "object",
      "description": "Information about the user who experienced the error.",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "description": "A unique identifier for the user."
        },
        "username": {
          "type": "string",
          "description": "The user's display name."
        },
        "email": {
          "type": "string",
          "description": "The user's email address.",
          "format": "email"
        }
      }
    }
  }
}