Anomaly Detection Anomaly Structure

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/anomaly-detection/refs/heads/main/json-structure/anomaly-detection-anomaly-structure.json",
  "description": "A detected anomaly in a time series or multivariate data stream, including the affected metric, timestamp, severity score, and contextual metadata.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the detected anomaly.",
      "example": "anom-500123"
    },
    "metric_name": {
      "type": "string",
      "description": "Name of the metric or signal in which the anomaly was detected.",
      "example": "cpu_utilization"
    },
    "timestamp": {
      "type": "datetime",
      "description": "ISO 8601 timestamp when the anomaly was detected.",
      "example": "2026-04-19T14:30:00Z"
    },
    "value": {
      "type": "double",
      "description": "The observed metric value at the time of the anomaly.",
      "example": 98.7
    },
    "expected_value": {
      "type": "double",
      "description": "The expected metric value based on historical patterns.",
      "example": 62.3
    },
    "anomaly_score": {
      "type": "double",
      "minimum": 0,
      "maximum": 1,
      "description": "Normalized anomaly severity score between 0 (normal) and 1 (highly anomalous).",
      "example": 0.94
    },
    "severity": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "critical"
      ],
      "description": "Categorical severity level of the anomaly.",
      "example": "high"
    },
    "direction": {
      "type": "string",
      "enum": [
        "above",
        "below",
        "both"
      ],
      "description": "Whether the anomaly is a spike above expected, a dip below, or bidirectional.",
      "example": "above"
    },
    "algorithm": {
      "type": "string",
      "description": "The detection algorithm that identified this anomaly.",
      "example": "SARIMA"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "resolved",
        "acknowledged",
        "suppressed"
      ],
      "description": "Current status of the anomaly alert.",
      "example": "active"
    },
    "series_id": {
      "type": "string",
      "description": "Identifier of the time series or data stream this anomaly belongs to.",
      "example": "ts-prod-cluster-01"
    },
    "dimensions": {
      "type": "object",
      "description": "Key-value pairs providing additional context dimensions for the anomaly (e.g., region, service, host).",
      "additionalProperties": {
        "type": "string"
      },
      "example": {
        "region": "us-east-1",
        "host": "web-server-42"
      }
    },
    "related_anomalies": {
      "type": "array",
      "description": "List of related anomaly IDs grouped in the same root cause cluster.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "metric_name",
    "timestamp",
    "value",
    "anomaly_score",
    "severity",
    "status"
  ],
  "name": "Anomaly"
}