Grafana Panel

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.github.io/grafana/json-schema/panel.json",
  "title": "Grafana Panel",
  "description": "Schema for a Grafana panel within a dashboard, defining visualization type, queries, field configuration, and layout position.",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique numeric ID within the dashboard"
    },
    "type": {
      "type": "string",
      "description": "Panel visualization plugin type",
      "examples": [
        "timeseries", "stat", "gauge", "bargauge", "table",
        "barchart", "piechart", "histogram", "heatmap", "state-timeline",
        "status-history", "text", "logs", "nodeGraph", "traces",
        "flamegraph", "geomap", "canvas", "candlestick", "trend",
        "news", "dashlist", "alertlist", "annolist", "row"
      ]
    },
    "title": {
      "type": "string",
      "description": "Panel title displayed in the header"
    },
    "description": {
      "type": "string",
      "description": "Panel description, shown on hover over the info icon"
    },
    "transparent": {
      "type": "boolean",
      "default": false,
      "description": "Whether to display the panel without a background"
    },
    "gridPos": {
      "type": "object",
      "description": "Panel position and size on the dashboard grid (24 columns wide)",
      "properties": {
        "h": {
          "type": "integer",
          "minimum": 1,
          "description": "Panel height in grid units"
        },
        "w": {
          "type": "integer",
          "minimum": 1,
          "maximum": 24,
          "description": "Panel width in grid units (max 24)"
        },
        "x": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23,
          "description": "Panel x position (column)"
        },
        "y": {
          "type": "integer",
          "minimum": 0,
          "description": "Panel y position (row)"
        }
      },
      "required": ["h", "w", "x", "y"]
    },
    "datasource": {
      "type": ["object", "null"],
      "description": "Default data source for this panel",
      "properties": {
        "type": {
          "type": "string",
          "description": "Data source plugin type"
        },
        "uid": {
          "type": "string",
          "description": "Data source UID"
        }
      }
    },
    "targets": {
      "type": "array",
      "description": "Query targets - structure varies by data source type",
      "items": {
        "type": "object",
        "properties": {
          "refId": {
            "type": "string",
            "description": "Reference ID for the query (A, B, C, ...)"
          },
          "datasource": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "uid": { "type": "string" }
            }
          },
          "expr": {
            "type": "string",
            "description": "PromQL expression (Prometheus/Mimir/Thanos)"
          },
          "rawSql": {
            "type": "string",
            "description": "Raw SQL query (MySQL, PostgreSQL, MSSQL)"
          },
          "query": {
            "type": "string",
            "description": "Generic query field (Loki LogQL, Elasticsearch, etc.)"
          },
          "format": {
            "type": "string",
            "description": "Response format"
          },
          "legendFormat": {
            "type": "string",
            "description": "Legend label template"
          },
          "interval": {
            "type": "string",
            "description": "Minimum step interval"
          },
          "instant": {
            "type": "boolean",
            "description": "Whether to execute as an instant query"
          },
          "range": {
            "type": "boolean",
            "description": "Whether to execute as a range query"
          },
          "hide": {
            "type": "boolean",
            "description": "Whether to hide this query from visualization"
          },
          "editorMode": {
            "type": "string",
            "enum": ["code", "builder"]
          }
        },
        "required": ["refId"]
      }
    },
    "fieldConfig": {
      "type": "object",
      "description": "Field display configuration",
      "properties": {
        "defaults": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "description": "Unit of measurement, e.g. bytes, percent, s, ms, reqps"
            },
            "min": { "type": "number" },
            "max": { "type": "number" },
            "decimals": { "type": "integer" },
            "displayName": { "type": "string" },
            "noValue": { "type": "string" },
            "color": {
              "type": "object",
              "properties": {
                "mode": {
                  "type": "string",
                  "enum": ["palette-classic", "fixed", "continuous-GrYlRd", "continuous-BlYlRd", "continuous-blues", "continuous-reds", "continuous-greens", "continuous-purples", "shades"]
                },
                "fixedColor": { "type": "string" }
              }
            },
            "thresholds": {
              "type": "object",
              "properties": {
                "mode": {
                  "type": "string",
                  "enum": ["absolute", "percentage"]
                },
                "steps": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "color": { "type": "string" },
                      "value": { "type": ["number", "null"] }
                    },
                    "required": ["color", "value"]
                  }
                }
              }
            },
            "mappings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["value", "range", "regex", "special"]
                  },
                  "options": { "type": "object" }
                }
              }
            },
            "links": {
              "type": "array",
              "items": { "type": "object" }
            },
            "custom": {
              "type": "object",
              "description": "Panel-type-specific field configuration"
            }
          }
        },
        "overrides": {
          "type": "array",
          "description": "Field-specific overrides",
          "items": {
            "type": "object",
            "properties": {
              "matcher": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "enum": ["byName", "byRegexp", "byType", "byFrameRefID"]
                  },
                  "options": {}
                }
              },
              "properties": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "value": {}
                  }
                }
              }
            }
          }
        }
      }
    },
    "options": {
      "type": "object",
      "description": "Panel-type-specific visualization options. Structure depends on the panel type."
    },
    "transformations": {
      "type": "array",
      "description": "Data transformations applied before visualization",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Transformation type, e.g. merge, organize, filterFieldsByName, reduce, groupBy, joinByField, calculateField, sortBy"
          },
          "options": {
            "type": "object",
            "description": "Transformation-specific options"
          },
          "disabled": {
            "type": "boolean"
          },
          "filter": {
            "type": "object"
          }
        },
        "required": ["id", "options"]
      }
    },
    "repeat": {
      "type": "string",
      "description": "Template variable name to repeat this panel for each value"
    },
    "repeatDirection": {
      "type": "string",
      "enum": ["h", "v"],
      "description": "Direction to repeat panels: h (horizontal) or v (vertical)"
    },
    "maxPerRow": {
      "type": "integer",
      "description": "Maximum number of panels per row when repeating horizontally"
    },
    "links": {
      "type": "array",
      "description": "Panel-level links",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string" },
          "targetBlank": { "type": "boolean" }
        }
      }
    },
    "alert": {
      "type": "object",
      "description": "Legacy alerting rule attached to the panel (deprecated in favor of unified alerting)"
    },
    "collapsed": {
      "type": "boolean",
      "description": "Only for row panels - whether the row is collapsed"
    },
    "panels": {
      "type": "array",
      "description": "Only for row panels - nested panels within a collapsed row",
      "items": { "$ref": "#" }
    }
  },
  "required": ["type", "gridPos"]
}