{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://chartkit.dev/schema/v1.json",
  "title": "ChartKit chart spec v1",
  "description": "A complete, framework-agnostic description of one chart. The same JSON renders in React, Vue, Svelte, and vanilla JS. Minimal line chart: {version, type, data, encoding:{x,y}, a11y:{alt}}. Everything else has sensible defaults.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "version",
    "type",
    "a11y"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://chartkit.dev/schema/v1.json",
      "description": "Schema URL. Lets editors and agents autocomplete and validate."
    },
    "version": {
      "type": "string",
      "const": "1",
      "description": "Spec major version. Always '1' for this schema."
    },
    "type": {
      "enum": [
        "line",
        "bar",
        "donut",
        "pie",
        "stacked-area",
        "scatter",
        "combo",
        "heatmap",
        "gauge",
        "kpi",
        "sparkline",
        "mini-area",
        "progress-ring",
        "spike",
        "candlestick",
        "histogram",
        "boxplot",
        "radar",
        "funnel",
        "treemap",
        "sankey",
        "bullet",
        "waterfall",
        "area-range",
        "bar-range",
        "errorbar",
        "sunburst",
        "tree",
        "bar-list",
        "radial-bar",
        "rose",
        "strip",
        "streamgraph",
        "density"
      ],
      "examples": [
        "line"
      ],
      "description": "Chart type. Put it in type, never in mark (mark is an options object). 'line': Lines over a continuous x (usually time). One or more y fields. Replaces LineChart. 'bar': Bars per category (x). Grouped or stacked; vertical or horizontal. Replaces BarChart. 'donut': Parts of a whole. x = slice category, y = slice value; not theta or angle. Replaces DonutChart. 'pie': The same slices with no hole. mark.startAngle, mark.padAngle, mark.cornerRadius, mark.sort, mark.other, and mark.explode. Outside labels draw leader lines. 'stacked-area': Stacked areas over time; each y field (or each series value) is a layer. Replaces StackedArea. 'scatter': Points by two quantitative fields; optional size (bubble) and color (category). Replaces ScatterChart. 'combo': Mixed bar/line/area series sharing x, with optional second y axis. Each y item sets its own mark. Replaces ComboChart. 'heatmap': Color-encoded cells. encoding.y present and mark.layout omitted means grid (x by y). mark.layout 'calendar' = date x by weekday; 'grid' = x by y matrix. Replaces Heatmap. 'gauge': Single value on a semicircular scale with optional bands and target. Uses metric, not top-level value/min/max. Replaces GaugeChart. 'kpi': Metric card: metric.label, metric.value, metric.delta, optional sparkline from data. Replaces KpiCard. 'sparkline': Tiny axis-less trend line. data may be a plain number array. Replaces Sparkline. 'mini-area': Tiny axis-less filled area. data may be a plain number array. Replaces MiniArea. 'progress-ring': Circular progress for a single value between metric.min and metric.max. Replaces ProgressRing. 'spike': Event/spike chart: thin vertical spikes from a baseline over time. Replaces SpikeChart. 'candlestick': Financial OHLC candles; requires x, open, high, low, close; optional volume. Replaces CandlestickChart. 'histogram': Bins quantitative encoding.x. mark.bins (default 8), mark.binWidth, or mark.bin (count, width, sturges, sqrt, fd). encoding.y, when present, is a pre-binned count. 'boxplot': encoding.x is the category and encoding.y holds the observations. 'radar': encoding.x is the spoke and encoding.y is one field or a list of series. 'funnel': encoding.x is the stage and encoding.y is the value, in data order. 'treemap': encoding.x is the tile, encoding.y is the size, and encoding.color is an optional group. Nested children, encoding.path, or encoding.id with encoding.parent draw nested levels; a flat treemap stays one level. 'sunburst': concentric rings for that same hierarchy. Colour follows the top-level branch. mark.innerRadius is the hole (0.28 when omitted) and mark.depth caps the rings. 'sankey': encoding.source, encoding.target, and encoding.y (the flow). 'bullet': encoding.x is the label, encoding.y the measure, encoding.target the goal. mark.ranges names band fields, worst to best. 'waterfall': encoding.x is the step and encoding.y is the delta. mark.total names a field that marks an absolute total bar. 'area-range': a band between low and high, with an optional centre line from y. Several bands are a y list of {lo, hi}. 'bar-range': a floating bar from low to high per category. 'errorbar': whiskers on a point or a bar, from low and high or from encoding.error as ± around y. A combo y item with mark range and lo/hi draws that band under the other series. 'bar-list': Ranked rows with no axes. A tinted track runs behind the label and the value sits at the right. Load it from @chartkitdev/core/charts/bar-list. It is not in the line or all bundle. 'radial-bar': category on x, radius on y, bars around a circle. Several y fields group side by side unless mark.stack is stack or percent. 'rose': equal angles, and the radius is the value (a nightingale rose). Both use polar coordinates and load from @chartkitdev/core/charts/<type>. They are not in the line bundle. layout.coordinate polar on bar, pie, or donut repairs onto radial-bar or rose (CK3077). 'strip': One row per group (a column when mark.orientation is vertical). Each observation is a dot on a shared numeric axis. Omit mark.orientation for horizontal: encoding.y is the group and encoding.x is the value. Vertical swaps those. mark.summary is a median tick unless set to mean or none. mark.band is none, range (min to max), or iqr. mark.jitter is none, auto, or a pixel distance. mark.highlight names one group, drawn in accent. encoding.label is the point name in the tooltip. A compare annotation draws a bracket between two groups. Load it from @chartkitdev/core/charts/strip. It is not in the line or all bundle. 'density': A kernel density estimate of encoding.x. Rows stay the raw sample. mark.bandwidth defaults to auto (Scott's rule). mark.steps defaults to 64. Groups overlay. Load it from @chartkitdev/core/charts/density. It is not in the line or all bundle. 'streamgraph': A stacked area around a moving baseline. mark.streamOffset defaults to wiggle (center, silhouette, zero, or expand). mark.order defaults to inside-out when the baseline wiggles. The y axis is in offset space, and the tooltip reports the raw value. Load it from @chartkitdev/core/charts/streamgraph. It is not in the line or all bundle. 'tree': A tidy node-link layout of one hierarchy. mark.tree cluster lines the leaves up (a dendrogram). Dots and short labels, not boxes. Load it from @chartkitdev/core/charts/tree. It is not in the line or all bundle."
    },
    "id": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
      "description": "Optional stable id (used for keys, events, test hooks)."
    },
    "title": {
      "type": "string",
      "description": "Visible chart title; also the accessible name."
    },
    "subtitle": {
      "type": "string",
      "description": "Visible secondary line under the title."
    },
    "headline": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "label": {
          "type": "string",
          "description": "Small label above the value."
        },
        "value": {
          "type": "string",
          "description": "Primary figure, drawn in the chart."
        },
        "compare": {
          "type": "string",
          "description": "Secondary comparison figure, in the muted colour."
        },
        "delta": {
          "type": "string",
          "description": "Change badge, drawn as a pill."
        },
        "tone": {
          "enum": ["positive", "negative", "neutral"],
          "description": "Pill colour. positive uses the positive token, negative the negative token."
        }
      },
      "description": "Figure, comparison, and delta pill drawn above the plot."
    },
    "data": {
      "$ref": "#/$defs/data"
    },
    "encoding": {
      "$ref": "#/$defs/encoding"
    },
    "metric": {
      "$ref": "#/$defs/metric"
    },
    "mark": {
      "$ref": "#/$defs/mark"
    },
    "axes": {
      "$ref": "#/$defs/axes"
    },
    "legend": {
      "$ref": "#/$defs/legend"
    },
    "tooltip": {
      "$ref": "#/$defs/tooltip"
    },
    "annotations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/annotation"
      },
      "description": "Reference rules, bands, text, trendlines, regression fits, and point callouts."
    },
    "theme": {
      "$ref": "#/$defs/theme"
    },
    "size": {
      "$ref": "#/$defs/size"
    },
    "layout": {
      "$ref": "#/$defs/layout"
    },
    "interaction": {
      "$ref": "#/$defs/interaction"
    },
    "animation": {
      "$ref": "#/$defs/animation"
    },
    "motion": {
      "$ref": "#/$defs/motion"
    },
    "render": {
      "enum": ["svg", "canvas", "auto"],
      "default": "svg",
      "description": "How the marks are drawn. svg is the default and what render() always returns, including on the server, with the marks included. canvas paints line, stacked-area, scatter, bar, heatmap, and candlestick marks from the computed geometry onto a 2D canvas. The client SVG keeps the axes, legend, title, annotations, the aria description, and the data table. Hit-testing reads the data: binary search on x for line, area, and bar, and a grid for scatter. auto uses canvas for those types once the table has 100000 or more rows. Other types stay SVG and warn CK3033. The canvas painter loads on demand and is not part of createRenderer([line])."
    },
    "locale": {
      "type": "string",
      "examples": [
        "en-US",
        "de-DE"
      ],
      "description": "BCP 47 locale for number/date formatting. Default: the host's locale."
    },
    "timezone": {
      "type": "string",
      "examples": ["UTC", "America/New_York"],
      "description": "IANA time zone for temporal axes, ticks, and tooltips. Omitted means UTC, so a server render and the client label the same instant the same way."
    },
    "sort": {
      "type": "object",
      "additionalProperties": false,
      "description": "Sort rows before drawing. field sorts by that column. by value sorts categories by the first y field. order is ascending (default) or descending.",
      "properties": {
        "field": {
          "type": "string",
          "description": "Field to sort by."
        },
        "by": {
          "enum": ["value"],
          "description": "Sort by the first y value. Used for bars."
        },
        "order": {
          "enum": ["ascending", "descending"],
          "description": "Sort direction. Default ascending."
        }
      }
    },
    "transform": {
      "type": "array",
      "description": "Row steps applied before sort: filter, a rolling window, or an aggregate.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "type": {
            "enum": ["filter", "window", "aggregate"],
            "description": "filter keeps matching rows. window adds a rolling column. aggregate groups rows."
          },
          "field": {
            "type": "string",
            "description": "Source field. Required for filter and window, and for sum or mean."
          },
          "eq": {
            "type": ["string", "number", "boolean", "null"],
            "description": "filter: keep rows whose field equals this."
          },
          "gt": {
            "type": "number",
            "description": "filter: keep rows greater than this."
          },
          "gte": {
            "type": "number",
            "description": "filter: keep rows greater than or equal to this."
          },
          "lt": {
            "type": "number",
            "description": "filter: keep rows less than this."
          },
          "lte": {
            "type": "number",
            "description": "filter: keep rows less than or equal to this."
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "description": "window: number of rows in the rolling window, including the current row."
          },
          "op": {
            "enum": ["mean", "sum", "count"],
            "description": "window defaults to mean. aggregate is sum, mean, or count."
          },
          "as": {
            "type": "string",
            "description": "Output field name. window requires it. aggregate defaults to the source field, or count."
          },
          "group": {
            "type": "string",
            "description": "aggregate: field to group by."
          }
        }
      }
    },
    "a11y": {
      "$ref": "#/$defs/a11y"
    }
  },
  "allOf": [
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "line",
              "bar",
              "donut",
              "pie",
              "stacked-area",
              "scatter",
              "combo",
              "heatmap",
              "sparkline",
              "mini-area",
              "spike",
              "candlestick",
              "histogram",
              "boxplot",
              "radar",
              "funnel",
              "treemap",
              "sankey",
              "bullet",
              "waterfall",
              "area-range",
              "bar-range",
              "errorbar",
              "sunburst",
              "radial-bar",
              "rose",
              "strip",
              "streamgraph",
              "density",
              "tree"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "data"
        ]
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "line",
              "bar",
              "donut",
              "stacked-area",
              "combo",
              "boxplot",
              "radar",
              "funnel",
              "treemap",
              "bullet",
              "waterfall",
              "area-range",
              "errorbar",
              "radial-bar",
              "rose",
              "strip",
              "streamgraph"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "encoding"
        ],
        "properties": {
          "encoding": {
            "type": "object",
            "required": [
              "x",
              "y"
            ]
          }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "scatter"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "encoding"
        ],
        "properties": {
          "encoding": {
            "type": "object",
            "required": [
              "x",
              "y"
            ]
          }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "heatmap"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "encoding"
        ],
        "properties": {
          "encoding": {
            "type": "object",
            "required": [
              "x",
              "color"
            ]
          }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "candlestick"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "encoding"
        ],
        "properties": {
          "encoding": {
            "type": "object",
            "required": [
              "x",
              "open",
              "high",
              "low",
              "close"
            ]
          }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "gauge",
              "progress-ring",
              "kpi"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "metric"
        ]
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "histogram",
              "density"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "encoding"
        ],
        "properties": {
          "encoding": {
            "type": "object",
            "required": [
              "x"
            ]
          }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": {
          "type": {
            "enum": [
              "sankey"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "encoding"
        ],
        "properties": {
          "encoding": {
            "type": "object",
            "required": [
              "source",
              "target",
              "y"
            ]
          }
        }
      }
    }
  ],
  "$defs": {
    "fieldName": {
      "type": "string",
      "minLength": 1,
      "description": "Name of a column in data (row key or columns key). Case-sensitive."
    },
    "color": {
      "type": "string",
      "minLength": 1,
      "description": "A CSS color ('#22c55e', 'rgb(...)', 'oklch(...)'), a CSS variable ('var(--chart-1)'), or a theme token reference: 'series-1'..'series-12', 'accent', 'positive', 'negative', 'text', 'muted', 'grid'."
    },
    "format": {
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "number",
            "integer",
            "compact",
            "percent",
            "percent-raw",
            "currency",
            "bytes",
            "duration-ms",
            "duration-hm",
            "date",
            "time",
            "datetime",
            "month",
            "year",
            "weekday"
          ],
          "description": "Preset. 'number' 1,234.5 · 'integer' 1,235 · 'compact' 1.2K · 'percent' treats 0.25 as 25% · 'percent-raw' treats 25 as 25% · 'currency' uses USD unless formatObject is used · 'bytes' 1.2 MB · 'duration-ms' 1.2s · 'duration-hm' 2m 24s · 'date' Oct 16, 2026 · 'time' 08:42 · 'datetime' · 'month' Oct · 'year' 2026 · 'weekday' Fri."
        },
        {
          "$ref": "#/$defs/formatObject"
        }
      ],
      "description": "How values are displayed in axes, tooltips and labels. A preset string, or an object for fine control. Formatting uses Intl with the spec 'locale'."
    },
    "formatObject": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "style": {
          "enum": [
            "number",
            "compact",
            "percent",
            "percent-raw",
            "currency",
            "bytes",
            "duration-ms",
            "duration-hm",
            "date",
            "time",
            "datetime"
          ],
          "description": "Base format style. 'duration-hm' prints minutes and seconds, such as 2m 24s."
        },
        "decimals": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10,
          "description": "Fixed number of fraction digits."
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "examples": [
            "USD",
            "EUR"
          ],
          "description": "ISO 4217 code when style is 'currency'."
        },
        "prefix": {
          "type": "string",
          "description": "Text placed before the value."
        },
        "suffix": {
          "type": "string",
          "description": "Text placed after the value, e.g. ' req/s'."
        },
        "signed": {
          "type": "boolean",
          "description": "Always show + for positive numbers (useful for deltas)."
        },
        "specifier": {
          "type": "string",
          "description": "d3-style format: .2f, ,.0f, $,.0f, .1%, .2e, +.1f, or s. A string format such as \".2f\" is repaired to this."
        }
      },
      "description": "Detailed format."
    },
    "scale": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "type": {
          "enum": [
            "linear",
            "log",
            "sqrt",
            "time",
            "band",
            "point",
            "symlog"
          ],
          "description": "Scale type. Inferred from field type: quantitative→linear, temporal→time, nominal/ordinal→band. symlog is a signed log that passes through zero."
        },
        "domain": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": [
              "number",
              "string",
              "null"
            ]
          },
          "description": "Explicit [min, max] for continuous scales, or the ordered list of categories for band/point scales. Use null for one side to keep it automatic."
        },
        "zero": {
          "type": "boolean",
          "description": "Force the scale to include zero. Default true for bar/area, false for line/scatter."
        },
        "nice": {
          "type": "boolean",
          "description": "Round the domain to tidy tick values. Default true."
        },
        "reverse": {
          "type": "boolean",
          "description": "Flip the direction of the scale."
        },
        "padding": {
          "description": "Extra room past the data, as a fraction of the span. A number pads both ends. An object pads one end. 0.08 is eight percent. An explicit domain end stays as set.",
          "oneOf": [
            { "type": "number", "minimum": 0, "maximum": 1 },
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "min": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of the span added below the data." },
                "max": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of the span added above the data." }
              }
            }
          ]
        },
        "clamp": {
          "type": "boolean",
          "description": "Draw values outside an explicit scale.domain at the domain edge."
        },
        "constant": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Linear half-width of a symlog scale, in data units. Default 1. Ignored unless type is symlog."
        }
      },
      "description": "How data values map to positions or sizes. Usually inferred; set only to override."
    },
    "colorScale": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "type": {
          "enum": ["linear", "log", "sqrt", "time", "band", "point", "sequential", "diverging", "quantize", "threshold"],
          "description": "Position types match the shared scale. sequential, diverging, quantize, and threshold are colour-only and are not valid on x or y."
        },
        "domain": {
          "type": "array",
          "minItems": 1,
          "items": { "type": ["number", "string", "null"] },
          "description": "Explicit [min, max] for a continuous colour scale."
        },
        "zero": { "type": "boolean", "description": "Force the scale to include zero." },
        "nice": { "type": "boolean", "description": "Round the domain to tidy values." },
        "reverse": { "type": "boolean", "description": "Flip the direction of the scale." },
        "midpoint": { "type": "number", "description": "Diverging midpoint. Default is the middle of the domain." },
        "scheme": {
          "enum": ["blue", "teal", "orange", "violet"],
          "description": "Named colour-blind-safe ramp. blue is the default. A range of two or more colours replaces it. Midnight uses a brighter ramp of the same name."
        },
        "bins": { "type": "integer", "minimum": 2, "description": "Equal-width bins for quantize. Default 5." },
        "thresholds": {
          "type": "array",
          "items": { "type": "number" },
          "description": "Cut points for threshold. Colours are one more than the number of cuts. The legend labels the cuts, for example <6, 6–12, ≥12, not the data ends."
        }
      },
      "description": "Colour scale. Sequential and diverging are continuous; quantize and threshold are binned."
    },
    "channel": {
      "oneOf": [
        {
          "$ref": "#/$defs/fieldName"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "field"
          ],
          "properties": {
            "field": {
              "$ref": "#/$defs/fieldName"
            },
            "type": {
              "enum": [
                "quantitative",
                "temporal",
                "ordinal",
                "nominal"
              ],
              "description": "Measurement type of the field. Inferred from data if omitted: numbers→quantitative, ISO date strings/epoch ms on x→temporal, other strings→nominal."
            },
            "title": {
              "type": "string",
              "description": "Human-readable name used in axes, legend and tooltip. Defaults to the field name."
            },
            "format": {
              "$ref": "#/$defs/format"
            },
            "scale": {
              "$ref": "#/$defs/scale"
            }
          },
          "description": "Full channel definition."
        }
      ],
      "description": "Maps a data field to a visual channel. Shorthand: a plain string is the field name."
    },
    "yChannel": {
      "oneOf": [
        {
          "$ref": "#/$defs/fieldName"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "#/$defs/fieldName"
            },
            "lo": {
              "type": "string",
              "description": "Lower field of a range band. With hi, the series is a band. On a combo, set mark to range so the band sits under the other series."
            },
            "hi": {
              "type": "string",
              "description": "Upper field of a range band."
            },
            "error": {
              "type": "string",
              "description": "± field around this series. Half-width. Used by error bars when low and high are omitted."
            },
            "type": {
              "enum": [
                "quantitative",
                "temporal",
                "ordinal",
                "nominal"
              ],
              "description": "Measurement type of the field. Inferred from data if omitted: numbers→quantitative, ISO date strings/epoch ms on x→temporal, other strings→nominal."
            },
            "title": {
              "type": "string",
              "description": "Human-readable name used in axes, legend and tooltip. Defaults to the field name."
            },
            "format": {
              "$ref": "#/$defs/format"
            },
            "scale": {
              "$ref": "#/$defs/scale"
            },
            "mark": {
              "enum": [
                "line",
                "bar",
                "area",
                "range"
              ],
              "description": "Mark for this series. line, bar, and area are for combo. range draws a lo/hi band under the other combo series. A range series sets lo and hi instead of, or as well as, field."
            },
            "axis": {
              "enum": [
                "y",
                "y2"
              ],
              "default": "y",
              "examples": [
                "y",
                "y2"
              ],
              "description": "Which y axis this series uses. The string \"y\" or \"y2\", not an axis object. 'y2' draws a second axis on the right. Put titles in axes.y.title or axes.y2.title."
            },
            "color": {
              "$ref": "#/$defs/color"
            },
            "dash": {
              "enum": [
                "solid",
                "dashed",
                "dotted"
              ],
              "default": "solid",
              "description": "Line style."
            },
            "area": {
              "type": "boolean",
              "description": "Fill under this line (line/combo)."
            },
            "fillOpacity": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Area or bar fill opacity for this series, 0–1. Overrides mark.fillOpacity."
            },
            "pointShape": {
              "enum": ["circle", "square", "diamond", "triangle", "cross", "none"],
              "description": "Marker for this series. Overrides mark.pointShape. Applies to: line, stacked-area, scatter, combo."
            },
            "pointSize": {
              "type": "number",
              "minimum": 0,
              "maximum": 40,
              "description": "Marker radius in px for this series. Overrides mark.pointSize."
            },
            "pointFill": {
              "enum": ["filled", "hollow"],
              "description": "Filled or hollow marker for this series. Overrides mark.pointFill."
            },
            "stack": {
              "type": "string",
              "minLength": 1,
              "description": "Stack group. Series that share this name stack together. A name used once draws that series unstacked. Omit it to follow mark.stack."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Stacked series keep data order."
            }
          },
          "description": "Full y series definition. field, or both lo and hi, is required."
        }
      ],
      "description": "A y series. Shorthand: a plain string is the field name."
    },
    "colorChannel": {
      "oneOf": [
        {
          "$ref": "#/$defs/fieldName"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "field"
          ],
          "properties": {
            "field": {
              "$ref": "#/$defs/fieldName"
            },
            "type": {
              "enum": [
                "quantitative",
                "temporal",
                "ordinal",
                "nominal"
              ],
              "description": "Measurement type of the field. Inferred from data if omitted: numbers→quantitative, ISO date strings/epoch ms on x→temporal, other strings→nominal."
            },
            "title": {
              "type": "string",
              "description": "Human-readable name used in axes, legend and tooltip. Defaults to the field name."
            },
            "format": {
              "$ref": "#/$defs/format"
            },
            "scale": {
              "$ref": "#/$defs/colorScale"
            },
            "range": {
              "type": "array",
              "minItems": 2,
              "items": {
                "$ref": "#/$defs/color"
              },
              "description": "Colors to use, in order (categorical) or low→high (sequential). Two or more colours replace a named scheme."
            },
            "domain": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string"
              },
              "description": "Category values in the same order as range. A value that is not listed takes the next palette colour."
            }
          },
          "description": "Color by field."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "value"
          ],
          "properties": {
            "value": {
              "$ref": "#/$defs/color"
            }
          },
          "description": "Constant color for every mark."
        }
      ],
      "description": "Color by a field (categorical or sequential), or a constant color. Shorthand: a plain string is a field name."
    },
    "sizeChannel": {
      "oneOf": [
        {
          "$ref": "#/$defs/fieldName"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "field"
          ],
          "properties": {
            "field": {
              "$ref": "#/$defs/fieldName"
            },
            "type": {
              "enum": [
                "quantitative",
                "temporal",
                "ordinal",
                "nominal"
              ],
              "description": "Measurement type of the field. Inferred from data if omitted: numbers→quantitative, ISO date strings/epoch ms on x→temporal, other strings→nominal."
            },
            "title": {
              "type": "string",
              "description": "Human-readable name used in axes, legend and tooltip. Defaults to the field name."
            },
            "format": {
              "$ref": "#/$defs/format"
            },
            "scale": {
              "$ref": "#/$defs/scale"
            },
            "range": {
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "items": {
                "type": "number",
                "minimum": 0
              },
              "default": [
                3,
                24
              ],
              "description": "[min, max] point radius in px."
            }
          },
          "description": "Size by field."
        }
      ],
      "description": "Map a quantitative field to point area (bubble chart). Shorthand: a plain string is the field name."
    },
    "encoding": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "x": {
          "$ref": "#/$defs/channel",
          "description": "Horizontal position: time or category. For donut, the slice category. For heatmap calendar, the date. For bar with mark.orientation 'horizontal', it is still the category (drawn vertically)."
        },
        "y": {
          "oneOf": [
            {
              "$ref": "#/$defs/yChannel"
            },
            {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/$defs/yChannel"
              },
              "description": "Multiple series, one per field."
            }
          ],
          "description": "Measured value(s). One field, or a list of fields for multi-series 'wide' data (one column per series). For heatmap 'grid' layout, the row category."
        },
        "series": {
          "$ref": "#/$defs/channel",
          "description": "Split 'long' data into series by the values of this field (e.g. region). Alternative to listing several y fields. Do not combine with a y array."
        },
        "color": {
          "$ref": "#/$defs/colorChannel",
          "description": "Color by field or a constant. Heatmap: the value field. Scatter: category field. Defaults to series/theme palette."
        },
        "size": {
          "$ref": "#/$defs/sizeChannel",
          "description": "Scatter only: bubble size field."
        },
        "open": {
          "$ref": "#/$defs/channel",
          "description": "Candlestick only: opening price field."
        },
        "high": {
          "$ref": "#/$defs/channel",
          "description": "Upper value. Candlestick: the high price. Area range, floating bar, and error bar: the top of the band or whisker."
        },
        "low": {
          "$ref": "#/$defs/channel",
          "description": "Lower value. Candlestick: the low price. Area range, floating bar, and error bar: the bottom of the band or whisker."
        },
        "close": {
          "$ref": "#/$defs/channel",
          "description": "Candlestick only: closing price field."
        },
        "volume": {
          "$ref": "#/$defs/channel",
          "description": "Candlestick only: volume field. When set, bars are drawn under the price plot."
        },
        "source": {
          "$ref": "#/$defs/channel",
          "description": "Sankey only: the node the flow leaves."
        },
        "target": {
          "$ref": "#/$defs/channel",
          "description": "Sankey: the node the flow enters. Bullet: the target value field."
        },
        "error": {
          "$ref": "#/$defs/channel",
          "description": "Error bar only: symmetric ± around y. The field is the half-width. encoding.low and encoding.high override it."
        },
        "path": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "type": "string"
          },
          "description": "Treemap and sunburst: field names from the root down to the leaf, for flat rows. A parent with no value is the sum of its leaves."
        },
        "id": {
          "type": "string",
          "description": "Treemap and sunburst: the node id field. Pair it with encoding.parent."
        },
        "parent": {
          "type": "string",
          "description": "Treemap and sunburst: the parent id field. An empty parent is a root. On a treemap with no encoding.id, a legacy parent field still repairs to encoding.color."
        },
        "label": {
          "$ref": "#/$defs/channel",
          "description": "Strip only: field shown with the group and the value in the point tooltip. It is not drawn on the plot. Other chart types warn CK3094."
        },
        "note": {
          "$ref": "#/$defs/channel",
          "description": "Strip only: a second, smaller line under the category label. Every point in the group should carry the same note, such as 100k points. The label and the note stay centred on that group's line. Other chart types warn CK3135."
        }
      },
      "description": "Which data fields drive which visual channels. Same names for every chart type: x is the category or time axis, y is the measured value(s). Donut uses x (slice label) and y (slice value), not theta, angle, or label. A y series axis is the string \"y\" or \"y2\". Switching 'type' between line/bar/donut/stacked-area/combo needs no re-encoding."
    },
    "data": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "number",
                "string",
                "boolean",
                "null",
                "object",
                "array"
              ]
            }
          },
          "description": "Rows: one object per record, keys are field names. Values are numbers, strings (ISO 8601 dates are parsed on temporal fields), booleans, null, or nested objects and arrays (treemap and sunburst children)."
        },
        {
          "type": "array",
          "items": {
            "type": [
              "number",
              "null"
            ]
          },
          "description": "Plain numbers (sparkline, mini-area, spike only). Field name is 'value', x is the index."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "columns"
          ],
          "properties": {
            "columns": {
              "type": "object",
              "minProperties": 1,
              "additionalProperties": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "string",
                    "boolean",
                    "null"
                  ]
                }
              },
              "description": "Map of field name to values."
            },
            "sampling": {
              "enum": ["lttb", "minmax", "none"],
              "description": "Downsample line-like marks. lttb is largest-triangle-three-buckets. minmax keeps the minimum and maximum in each pixel column. none draws every point. Omit it to keep mark.sampling, which defaults to auto (minmax once the series is longer than twice the plot width). When set, this overrides mark.sampling. A very long series drawn with none warns CK3032."
            }
          },
          "description": "Columnar: equal-length arrays keyed by field name. Preferred for 10k+ points. In JS, arrays may be typed arrays (Float64Array)."
        }
      ],
      "examples": [
        [
          {
            "quarter": "Q1",
            "units": 40
          },
          {
            "quarter": "Q2",
            "units": 55
          }
        ]
      ],
      "description": "The data to plot. A plain array of row objects, not { values: [...] }. Sparkline, mini-area, and spike also accept a plain number array (x becomes the index). A columnar object { columns: { field: [...] } } is accepted for large data and maps directly to typed arrays."
    },
    "mark": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "curve": {
          "enum": [
            "linear",
            "monotone",
            "step",
            "step-before",
            "step-after"
          ],
          "default": "monotone",
          "description": "Line interpolation. monotone is monotone-x and stays inside the data, so a spike does not cross the low point or pass the peak. smooth, spline, and basis repair to monotone. Applies to: line, stacked-area, combo, sparkline, mini-area, streamgraph."
        },
        "sampling": {
          "enum": [
            "auto",
            "none",
            "lttb",
            "minmax"
          ],
          "default": "auto",
          "description": "Downsample the path when a series is longer than twice the plot width in pixels. 'auto' and 'minmax' keep the minimum and maximum original point in each pixel bucket (spikes stay). 'lttb' is largest-triangle-three-buckets and also keeps original points. 'none' draws every point. Applies to: line, stacked-area, combo (line and area series only), sparkline, mini-area, spike. Scatter, candlestick, bar, donut, heatmap, gauge, kpi, and progress-ring ignore it (CK3010). Axis extents and a11y.alt always use the full series. Hover vertices map back to those original indexes."
        },
        "points": {
          "enum": [
            "none",
            "hover",
            "always"
          ],
          "default": "hover",
          "description": "Show point markers on lines. Applies to: line, combo."
        },
        "track": {
          "enum": [
            "bar",
            "row"
          ],
          "default": "bar",
          "description": "Ranked-row track. bar is a short rounded bar. row is a full-height wash behind the label, width proportional to the value, with the count on the right. Applies to: bar-list."
        },
        "pointSize": {
          "type": "number",
          "minimum": 0,
          "maximum": 40,
          "description": "Point radius in px. Applies to: line, stacked-area, combo, scatter, errorbar, strip."
        },
        "pointShape": {
          "enum": ["circle", "square", "diamond", "triangle", "cross", "none"],
          "description": "Point marker. circle, square, diamond, triangle, cross, or none. A y series may override it. Applies to: line, stacked-area, scatter, combo. Drawn on createRenderer([line])."
        },
        "pointFill": {
          "enum": ["filled", "hollow"],
          "description": "Filled or hollow markers. Applies to: line, stacked-area, scatter, combo."
        },
        "area": {
          "type": "boolean",
          "description": "Fill under every line. Applies to: line, sparkline."
        },
        "fillOpacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Area/bar fill opacity, 0–1. Applies to: line, stacked-area, combo, mini-area, bar, streamgraph. A streamgraph defaults to 0.22."
        },
        "gradient": {
          "type": "boolean",
          "default": true,
          "description": "Fade area fills toward the baseline. Applies to: line, stacked-area, mini-area, sparkline."
        },
        "strokeWidth": {
          "type": "number",
          "minimum": 0,
          "maximum": 40,
          "description": "Line width in px. Applies to: line, stacked-area, combo, sparkline, mini-area, spike, progress-ring, gauge (arc width), streamgraph."
        },
        "glow": {
          "type": "boolean",
          "default": false,
          "description": "Soft glow behind the line. A blurred understroke and one filter, emitted only when true, on Soft and on midnight. Applies to: line, sparkline, combo."
        },
        "connectNulls": {
          "type": "boolean",
          "default": false,
          "description": "Draw through missing values instead of leaving gaps. Applies to: line, stacked-area, combo, sparkline, mini-area, streamgraph."
        },
        "stack": {
          "enum": [
            "none",
            "stack",
            "percent"
          ],
          "description": "Stacking for multiple series. 'percent' normalises each x to 100%. Applies to: bar, stacked-area (default 'stack'), combo bars, radial-bar, rose. On a polar chart, none groups the sectors and stack or percent runs outward from the hole. A streamgraph warns CK3098 and repair removes it. The streamgraph stack is mark.streamOffset."
        },
        "streamOffset": {
          "enum": ["wiggle", "center", "silhouette", "zero", "expand"],
          "default": "wiggle",
          "description": "Streamgraph baseline. wiggle minimizes layer-to-layer movement and is the default. center, also called silhouette, centers each column on zero. zero stacks on the axis. expand draws shares that sum to 1. One series repairs to zero. Other chart types warn CK3099. mark.baseline is the spike origin, and mark.offset pulls a pie slice."
        },
        "order": {
          "enum": ["inside-out", "none", "ascending", "descending"],
          "description": "Streamgraph layer order. Omitted means inside-out when the baseline is wiggle, and first-seen order otherwise. inside-out puts the smallest series in the middle. ascending and descending sort by the series sum. Other chart types warn CK3100."
        },
        "orientation": {
          "enum": [
            "vertical",
            "horizontal"
          ],
          "default": "vertical",
          "description": "Bar direction. vertical is the bar default. Strip treats an omission as horizontal: categories run down the y axis and the numeric axis is x. Set vertical to swap them. Density treats an omission as horizontal: the sample runs along x and the density along y. Applies to: bar, strip, density."
        },
        "cornerRadius": {
          "type": "number",
          "minimum": 0,
          "maximum": 40,
          "description": "Rounded corners in px. Applies to: bar, donut, pie, heatmap, radial-bar, rose. A radial bar rounds the outer end."
        },
        "gap": {
          "type": "number",
          "minimum": 0,
          "maximum": 0.95,
          "description": "Spacing between bars/cells as a 0–1 fraction of the band. Applies to: bar, combo, heatmap, candlestick, radial-bar, rose. On a grouped polar chart it is the share of the category left between series."
        },
        "stackGap": {
          "type": "number",
          "minimum": 0,
          "maximum": 24,
          "description": "Pixel gap between stacked segments. Applies to: bar, stacked-area, combo."
        },
        "radiusEnds": {
          "enum": ["outer", "all"],
          "description": "Which bar corners round. outer rounds the end away from the baseline. all rounds every corner. Applies to: bar."
        },
        "partial": {
          "enum": ["dashed", "dotted"],
          "description": "Dash the last segment only. The area still covers the whole series, including that segment. Applies to: line, stacked-area, combo."
        },
        "partialOpacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Fill opacity of the last area segment. The earlier area keeps mark.fillOpacity. Applies to: line, stacked-area, combo."
        },
        "labels": {
          "type": "boolean",
          "default": false,
          "description": "Draw value labels on the marks. Applies to: bar, donut, pie, line, stacked-area, scatter, radial-bar, rose, streamgraph. A streamgraph label is the series name at the thickest part of the layer. Outside pie and donut labels use leader lines. Overlapping labels are skipped. A polar value is drawn on a sector tall enough to hold it."
        },
        "labelPosition": {
          "enum": ["top", "bottom", "left", "right", "center", "inside", "outside"],
          "description": "Where the value label sits. top, bottom, left, right, and center suit line, area, and scatter. inside and outside suit bar, donut, and pie. Outside pie and donut labels draw leader lines. Setting it turns labels on. Applies to: bar, donut, pie, line, stacked-area, scatter, combo."
        },
        "labelFormat": {
          "$ref": "#/$defs/format",
          "description": "Format preset for data labels. Falls back to the series format, then a plain number. Setting it turns labels on. On a strip it formats the end label, the note range, and the tooltip, and the axis ticks keep axes format. Applies to: bar, donut, pie, line, stacked-area, scatter, combo, strip."
        },
        "labelEnds": {
          "enum": ["all", "ends", "last"],
          "description": "Which line points are labelled. all, ends (first and last), or last. Setting it turns labels on. Applies to: line, stacked-area, combo."
        },
        "stackTotal": {
          "type": "boolean",
          "default": false,
          "description": "Label the total of a stacked bar or stacked area. On a bar this also stacks the series. Applies to: bar, stacked-area."
        },
        "innerRadius": {
          "type": "number",
          "minimum": 0,
          "maximum": 0.95,
          "default": 0.6,
          "description": "Hole size as a 0–0.95 fraction of the radius. Donut defaults to 0.6. Pie defaults to 0. Sunburst uses 0.28 when this is omitted. Radial-bar defaults to 0.34. Rose defaults to 0. Above 0.85 on a polar chart warns CK3075. Applies to: donut, pie, sunburst, radial-bar, rose."
        },
        "tree": {
          "enum": ["tidy", "cluster"],
          "default": "tidy",
          "description": "tidy is Reingold–Tilford. cluster lines the leaves up, which is the dendrogram. Applies to: tree."
        },
        "orient": {
          "enum": ["LR", "RL", "TB", "BT"],
          "default": "LR",
          "description": "Root on the left, right, top, or bottom. Applies to: tree."
        },
        "link": {
          "enum": ["curve", "step"],
          "default": "curve",
          "description": "A smooth link, or a right-angle step. step does not draw a box. Applies to: tree."
        },
        "radial": {
          "type": "boolean",
          "default": false,
          "description": "Root at the center and depth as the radius. Applies to: tree."
        },
        "colorBy": {
          "enum": ["branch", "depth"],
          "default": "branch",
          "description": "Color dots by the top-level branch or by depth. encoding.color wins when it names a field. Applies to: tree."
        },
        "collapsed": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Ids of nodes whose children are hidden. A click in mount() toggles an id. The static SVG uses this list. Applies to: tree."
        },
        "depth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 12,
          "description": "How many levels to draw under the root. Deeper nodes fold into that level. Default 8. Applies to: treemap, sunburst, tree."
        },
        "padAngle": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "Gap between slices in degrees. Donut defaults to 2. Pie defaults to 0. Radial-bar defaults to 2. Rose defaults to 1.2. Above 8 degrees on a polar chart warns CK3076. Applies to: donut, pie, radial-bar, rose."
        },
        "summary": {
          "enum": ["none", "median", "mean"],
          "default": "median",
          "description": "Tick drawn across each group. median is the default. mean is the arithmetic mean. none draws no tick. A strip where every group has one point hides the tick. Applies to: strip."
        },
        "band": {
          "enum": ["none", "range", "iqr"],
          "default": "none",
          "description": "Bar behind the dots. none draws none. range runs from the minimum to the maximum. iqr runs from the first quartile to the third. A group with fewer than 3 points draws no band. Applies to: strip."
        },
        "jitter": {
          "oneOf": [
            {
              "enum": ["none", "auto"]
            },
            {
              "type": "number",
              "minimum": 0,
              "maximum": 40,
              "description": "Maximum perpendicular offset in px."
            }
          ],
          "default": "auto",
          "description": "Spread dots that share a position. auto offsets a dot only when another dot in the group is within one diameter. none never offsets. A number is the maximum offset in px and moves every dot. The offset is a function of the row, so a server render matches the client. Applies to: strip."
        },
        "highlight": {
          "type": "string",
          "description": "Group or series value to emphasise. A group name marks that row. A series value, the color field, marks those dots. With mark.emphasis omitted or muted, the other marks use muted. Applies to: strip."
        },
        "emphasis": {
          "enum": ["muted", "ring", "color"],
          "description": "How mark.highlight is drawn. muted fades every other mark. ring draws the highlighted dots larger, with a ring, and keeps the other series colours. color paints the highlighted row in accent and keeps the other series colours. Omitted means muted when highlight is set. Applies to: strip."
        },
        "note": {
          "enum": ["none", "field", "range"],
          "default": "none",
          "description": "Second line under the category label. none draws none. field uses encoding.note. range draws the minimum and maximum and does not repeat them beside the end label. The two lines stay centred on the plotted line. Applies to: strip."
        },
        "notePrefix": {
          "type": "string",
          "description": "Text before the note, such as range followed by a space. Applies to: strip."
        },
        "pin": {
          "type": "boolean",
          "default": false,
          "description": "A value outside scale.domain is an edge marker with its real value, not a dot past the plot. Needs an explicit domain. Applies to: strip."
        },
        "pinFormat": {
          "$ref": "#/$defs/format",
          "description": "Format for a pin label. Defaults to mark.labelFormat, then the axis format. duration-ms prints 18.7 s. Applies to: strip."
        },
        "bandColor": {
          "enum": ["accent", "series"],
          "default": "accent",
          "description": "Fill of the range band. accent is one wash. series uses that row's colour at low opacity. Applies to: strip."
        },
        "value": {
          "enum": ["summary", "highlight"],
          "default": "summary",
          "description": "Number at the end of the row. summary is the median, the mean, or the first point when the tick is hidden. highlight is the highlighted series value in that row. Applies to: strip."
        },
        "labelColor": {
          "enum": ["text", "accent", "series"],
          "default": "text",
          "description": "Colour of the end label. text is ink. accent is the brand colour. series uses that row's colour, and a highlighted row stays accent. Applies to: strip."
        },
        "labelSuffix": {
          "type": "string",
          "description": "Smaller unit after the end label, such as ms or tok. It is not part of the tick format. Applies to: strip."
        },
        "zebra": {
          "type": "boolean",
          "default": false,
          "description": "Tint every other row, starting with the first. The tint sits behind the line. It is not a rule between rows. Applies to: strip."
        },
        "gutter": {
          "type": "number",
          "minimum": 0,
          "maximum": 240,
          "description": "Right margin for the end label, in px. Omitted, the margin fits the labels. A set value wins over that fit. size.width and size.height are never changed. Applies to: strip."
        },
        "sort": {
          "enum": ["none", "asc", "desc"],
          "default": "none",
          "description": "Slice order. none keeps data order and pins an Other bucket last. asc and desc sort by value, including Other. On a strip, none keeps the first-seen group order and asc or desc orders groups by the summary (by the median when mark.summary is none). Applies to: donut, pie, strip."
        },
        "other": {
          "oneOf": [
            {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Fold slices smaller than this fraction of the total into Other."
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": ["threshold"],
              "properties": {
                "threshold": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "Fold slices smaller than this fraction of the total."
                },
                "label": {
                  "type": "string",
                  "description": "Name of the folded slice. Default Other."
                }
              },
              "description": "Fold slices under threshold into one bucket."
            }
          ],
          "description": "Group small slices into one Other slice. A number is the fraction. Applies to: donut, pie."
        },
        "offset": {
          "type": "number",
          "minimum": 0,
          "maximum": 48,
          "description": "Pull slices out from the centre, in px. With mark.explode, only those slices move. Otherwise every slice moves. Applies to: donut, pie."
        },
        "explode": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Slice names to offset. Uses mark.offset, or 12px when offset is omitted. Applies to: donut, pie."
        },
        "palette": {
          "type": "array",
          "minItems": 1,
          "maxItems": 24,
          "items": {
            "$ref": "#/$defs/color"
          },
          "description": "Series colours for this chart, in order. Overrides the theme palette. Omit it to keep the theme tokens. Applies to: line, bar, scatter, combo, stacked-area, donut, pie."
        },
        "colorRules": {
          "type": "array",
          "maxItems": 8,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["color"],
            "properties": {
              "color": {
                "$ref": "#/$defs/color",
                "description": "Colour for values that match this rule. A theme token stays readable in midnight."
              },
              "label": {
                "type": "string",
                "description": "Legend and tooltip name for values that match. Omit it to use the colour token."
              },
              "test": {
                "enum": ["negative", "positive"],
                "description": "Match negative or positive values."
              },
              "lt": { "type": "number", "description": "Match values less than this." },
              "lte": { "type": "number", "description": "Match values less than or equal to this." },
              "gt": { "type": "number", "description": "Match values greater than this." },
              "gte": { "type": "number", "description": "Match values greater than or equal to this." },
              "eq": { "type": "number", "description": "Match this value." }
            },
            "description": "First matching rule sets the mark colour. label names it in the legend and tooltip. A rule with only color matches every value. A rule that paints bars is one square legend entry in that bar colour. A combo point that matches the same rule is an outline in that colour."
          },
          "description": "Conditional colours. First match wins and overrides the series or category colour. A bar rule's legend swatch is the bar fill. A rule colour within CIE76 delta-E 25 of a series colour in the same theme shifts to a distinct shade. Applies to: line, bar, scatter, combo, donut, pie."
        },
        "baseLabel": {
          "type": "string",
          "description": "Legend name for values that match no colour rule, such as Normal. The series entry is renamed to the series name plus this label, for example Reading: Normal, and it is a square when those values are bars. Omit it to keep the series name. Applies to: line, bar, combo."
        },
        "opacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Mark opacity 0–1. Applies to: scatter, spike."
        },
        "layout": {
          "enum": [
            "calendar",
            "grid"
          ],
          "default": "calendar",
          "description": "Heatmap layout. Omit it when encoding.y is set: the renderer uses grid. 'calendar' = weeks by weekdays from a date x (also the fallback when y is absent). 'grid' = x by y categories. Applies to: heatmap."
        },
        "weeks": {
          "type": "integer",
          "minimum": 1,
          "maximum": 104,
          "default": 52,
          "description": "Number of weeks shown in calendar layout, ending on the week of the latest day. Ignored on a grid heatmap. Cells stay square, or at most 1.5:1, and cap at 32px. Extra width centres the grid. Unsized calendars stay at 12px. Applies to: heatmap."
        },
        "startAngle": {
          "type": "number",
          "minimum": -360,
          "maximum": 360,
          "description": "Arc start in degrees (0 = top, clockwise). Applies to: gauge, progress-ring, donut, pie, radial-bar, rose. Polar charts start at 0, the top of the circle."
        },
        "endAngle": {
          "type": "number",
          "minimum": -360,
          "maximum": 360,
          "description": "Arc end in degrees. Applies to: gauge, progress-ring."
        },
        "linecap": {
          "enum": [
            "butt",
            "round",
            "square"
          ],
          "default": "round",
          "description": "Arc end style. Applies to: gauge, progress-ring."
        },
        "rings": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["value"],
            "properties": {
              "value": {
                "type": "number",
                "description": "Progress toward max."
              },
              "max": {
                "type": "number",
                "exclusiveMinimum": 0,
                "description": "Goal for this ring. Defaults to 1."
              },
              "color": {
                "$ref": "#/$defs/color"
              },
              "label": {
                "type": "string",
                "description": "Short name drawn under the rings."
              }
            },
            "description": "One concentric ring."
          },
          "description": "Concentric activity rings, outer first. Each item is {value, max, color, label}. Applies to: progress-ring."
        },
        "baseline": {
          "type": "number",
          "default": 0,
          "description": "Value spikes rise from. Applies to: spike."
        },
        "shape": {
          "enum": [
            "bar",
            "trapezoid"
          ],
          "default": "trapezoid",
          "description": "Funnel geometry. trapezoid is the default: each stage shares its bottom edge with the next stage and the width tapers with the value. bar draws centered rounded bars. Applies to: funnel."
        },
        "bins": {
          "type": "integer",
          "minimum": 1,
          "maximum": 60,
          "description": "Histogram bin count when mark.bin is count or omitted. Default 8. Applies to: histogram. A density warns CK3107 and repair removes it."
        },
        "bin": {
          "enum": [
            "count",
            "width",
            "sturges",
            "sqrt",
            "fd"
          ],
          "description": "Histogram bin rule. count uses mark.bins. width uses mark.binWidth. sturges, sqrt, and fd choose a count from the data. Applies to: histogram."
        },
        "binWidth": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Histogram bin width. Used when mark.bin is width. Applies to: histogram."
        },
        "binLabel": {
          "type": "boolean",
          "default": false,
          "description": "Draw the bin count at the top right of the plot, clear of the y ticks. Omit it and that corner stays empty. Applies to: histogram."
        },
        "bandwidth": {
          "description": "Gaussian kernel width in data units. auto is Scott's rule, 1.06 times the standard deviation times n to the power -1/5. A number must be greater than 0. Other chart types warn CK3111. Applies to: density.",
          "oneOf": [
            { "const": "auto" },
            { "type": "number", "exclusiveMinimum": 0 }
          ]
        },
        "steps": {
          "type": "integer",
          "minimum": 16,
          "maximum": 256,
          "default": 64,
          "description": "Samples along the density curve. Default 64. Other chart types warn CK3112. Applies to: density."
        },
        "extent": {
          "description": "Domain of the density curve. pad extends the sample by 3 bandwidths. data clips to the sample. A pair is the domain. Applies to: density.",
          "oneOf": [
            { "enum": ["pad", "data"] },
            {
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "items": { "type": "number" }
            }
          ]
        },
        "normalize": {
          "enum": ["density", "count"],
          "default": "density",
          "description": "density integrates to 1. count multiplies by the sample size. Applies to: density."
        },
        "dims": {
          "enum": [1, 2],
          "description": "1 is the kernel curve. 2 is not available yet and is CK3109. Applies to: density."
        },
        "rug": {
          "type": "boolean",
          "default": false,
          "description": "Draw a tick for each raw sample on the baseline. Applies to: density."
        },
        "ranges": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "maxItems": 5,
          "description": "Bullet band fields, worst to best. Each value is the upper edge of that band. Applies to: bullet."
        },
        "total": {
          "type": "string",
          "description": "Waterfall field that marks an absolute total when the row is true. Default field name total. Applies to: waterfall."
        },
        "line": {
          "type": "boolean",
          "description": "Centre line through encoding.y on a range area. Defaults on when y is set. false draws the band only. Applies to: area-range."
        },
        "stroke": {
          "type": "boolean",
          "default": false,
          "description": "Outline a range band. Off by default so a nested interval stays a fill in the line colour. Applies to: area-range."
        },
        "strokeDash": {
          "type": "boolean",
          "default": false,
          "description": "Dash the centre line where a band is present, and keep the earlier actuals solid. Both parts use the line colour. Applies to: area-range."
        },
        "error": {
          "enum": ["point", "bar"],
          "description": "Whisker anchor. point draws a marker at y. bar draws a bar from zero to y. Applies to: errorbar."
        }
      },
      "examples": [
        {
          "curve": "linear"
        }
      ],
      "description": "Visual options for the marks. An object, not the chart type (the type goes in type). Each option lists the types it applies to; options that do not apply to the chosen type are ignored with warning CK3010."
    },
    "metric": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "value"
      ],
      "properties": {
        "value": {
          "type": "number",
          "description": "The current value."
        },
        "label": {
          "type": "string",
          "description": "Short visible label, e.g. 'Revenue'."
        },
        "min": {
          "type": "number",
          "default": 0,
          "description": "Lower bound of the scale (gauge, progress-ring)."
        },
        "max": {
          "type": "number",
          "default": 100,
          "description": "Upper bound of the scale (gauge, progress-ring)."
        },
        "target": {
          "type": "number",
          "description": "Target marker value (gauge) or comparison value."
        },
        "delta": {
          "type": "number",
          "description": "Change vs previous period, as a fraction (0.125 = +12.5%) unless deltaFormat says otherwise (kpi)."
        },
        "deltaFormat": {
          "$ref": "#/$defs/format",
          "description": "Format for delta. Default 'percent' with signed: true."
        },
        "goodDirection": {
          "enum": [
            "up",
            "down"
          ],
          "default": "up",
          "description": "Which direction of delta is good (sets positive/negative color)."
        },
        "format": {
          "$ref": "#/$defs/format",
          "description": "Format for value."
        },
        "bands": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "number",
                "description": "Start value."
              },
              "to": {
                "type": "number",
                "description": "End value."
              },
              "color": {
                "$ref": "#/$defs/color"
              },
              "label": {
                "type": "string",
                "description": "Band label."
              }
            },
            "description": "A colored range."
          },
          "description": "Colored ranges on the gauge, e.g. good/warn/bad."
        },
        "thresholds": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["value", "color"],
            "properties": {
              "value": {
                "type": "number",
                "description": "The step applies when metric.value is at or above this."
              },
              "color": {
                "$ref": "#/$defs/color"
              },
              "label": {
                "type": "string",
                "description": "Name for the step. Not drawn."
              }
            },
            "description": "One colour step."
          },
          "description": "Colour the kpi surface from the value. The last step at or below metric.value wins. Applies to: kpi."
        }
      },
      "examples": [
        {
          "label": "Capacity",
          "value": 64,
          "min": 0,
          "max": 100
        }
      ],
      "description": "Single-value content for gauge, progress-ring and kpi. Put value, min, max, delta, and label here, not at the top level of the spec. Kpi may also set data for a sparkline."
    },
    "axes": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "x": {
          "oneOf": [
            {
              "type": "boolean",
              "description": "false hides the axis; true uses defaults."
            },
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Axis title. Defaults to the channel title (none for time axes)."
                },
                "format": {
                  "$ref": "#/$defs/format",
                  "description": "Tick label format. Defaults to the channel format. On a strip this formats the ticks only. The row end label uses mark.labelFormat."
                },
                "edgeLabel": {
                  "type": "string",
                  "description": "Label drawn at the high end of the axis, such as 5s+. It does not move the domain. Applies to: strip."
                },
                "ticks": {
                  "oneOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 50
                    },
                    {
                      "const": "ends",
                      "description": "Label only the first and last tick."
                    },
                    {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 50,
                      "items": {
                        "type": "number"
                      }
                    }
                  ],
                  "description": "Approximate tick count, the exact tick values, or \"ends\" for the first and last label only."
                },
                "grid": {
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "enum": [
                        "solid",
                        "dashed",
                        "dotted"
                      ]
                    }
                  ],
                  "description": "Grid lines from this axis."
                },
                "labels": {
                  "type": "boolean",
                  "default": true,
                  "description": "Show tick labels."
                },
                "position": {
                  "enum": [
                    "top",
                    "bottom",
                    "left",
                    "right"
                  ],
                  "description": "Axis side. Defaults: x bottom, y left, y2 right. A side perpendicular to the axis maps onto the nearer end."
                },
                "titlePosition": {
                  "enum": ["start", "center", "end"],
                  "description": "Where the title sits along the axis. start is the minimum end (left or bottom). end is the maximum end. Default center."
                },
                "titleRotate": {
                  "type": "number",
                  "minimum": -360,
                  "maximum": 360,
                  "description": "Axis title rotation in degrees. Default 0 on x, -90 on a left y axis, and 90 on a right y or y2 axis."
                },
                "autoSkip": {
                  "type": "boolean",
                  "description": "Skip tick labels that would overlap. false draws every label. When omitted, crowded category labels still tilt about -40 degrees if that fits, and numeric ticks skip only when they collide."
                },
                "labelWidth": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 240,
                  "description": "Maximum tick-label width in pixels. Longer labels wrap, then ellipsize."
                },
                "labelLines": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 6,
                  "description": "Maximum lines for a wrapped tick label. Enables wrapping at 72 pixels when labelWidth is omitted."
                },
                "line": {
                  "description": "Axis baseline. Off unless set. Color defaults to the axis token.",
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "show": {
                          "type": "boolean",
                          "description": "Draw the baseline."
                        },
                        "color": {
                          "type": "string",
                          "description": "Stroke color. Defaults to the axis token."
                        },
                        "width": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 8,
                          "description": "Stroke width in pixels."
                        },
                        "dash": {
                          "enum": ["solid", "dashed", "dotted"],
                          "description": "Stroke pattern."
                        }
                      }
                    }
                  ]
                },
                "tickMarks": {
                  "enum": ["inside", "outside", "none"],
                  "description": "Tick marks at labeled ticks. none is the default. inside points into the plot."
                },
                "tickLength": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 24,
                  "description": "Tick mark length in pixels. Setting it draws outside marks unless tickMarks says otherwise."
                },
                "rotate": {
                  "type": "number",
                  "description": "Tick label rotation in degrees. When omitted, crowded category labels rotate about -40 degrees unless autoSkip is true."
                },
                "offset": {
                  "type": "number",
                  "minimum": -80,
                  "maximum": 80,
                  "description": "Shift the baseline outward in pixels. Positive moves it away from the plot."
                },
                "crosses": {
                  "type": "number",
                  "description": "Data value where this axis crosses the other. 0 draws the axis through zero."
                },
                "minorTicks": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 8,
                  "description": "Minor tick marks between major ticks. 0 hides them."
                },
                "breaks": {
                  "type": "array",
                  "maxItems": 3,
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["from", "to"],
                    "properties": {
                      "from": { "type": "number", "description": "Start of the collapsed range, in data units." },
                      "to": { "type": "number", "description": "End of the collapsed range, in data units." },
                      "share": { "type": "number", "minimum": 0.15, "maximum": 0.7, "description": "Fraction of the axis from zero to this break when the segment below crosses zero; otherwise the fraction for that whole segment. Default 0.4." }
                    }
                  },
                  "description": "Ranges collapsed to a short gap. The break mark is drawn on the axis. When the segment below crosses zero, share is the fraction of the axis from zero to the break (default 0.4); otherwise share is the fraction for that whole segment. Ticks inside a break are omitted. The axis line stops at the top tick."
                },
                "bands": {
                  "description": "Shaded x ranges, or \"weekends\" to shade Saturday and Sunday when x is dates.",
                  "oneOf": [
                    {
                      "const": "weekends",
                      "description": "Shade Saturday and Sunday. Warns when x values are not dates."
                    },
                    {
                      "type": "array",
                      "items": { "$ref": "#/$defs/axisBand" },
                      "description": "Shaded ranges, such as a launch window."
                    }
                  ]
                }
              },
              "description": "Axis settings."
            }
          ],
          "description": "Axis options. Set to false to hide the axis."
        },
        "y": {
          "oneOf": [
            {
              "type": "boolean",
              "description": "false hides the axis; true uses defaults."
            },
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Axis title. Defaults to the channel title (none for time axes)."
                },
                "format": {
                  "$ref": "#/$defs/format",
                  "description": "Tick label format. Defaults to the channel format. On a strip this formats the ticks only. The row end label uses mark.labelFormat."
                },
                "edgeLabel": {
                  "type": "string",
                  "description": "Label drawn at the high end of the axis, such as 5s+. It does not move the domain. Applies to: strip."
                },
                "ticks": {
                  "oneOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 50
                    },
                    {
                      "const": "ends",
                      "description": "Label only the first and last tick."
                    },
                    {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 50,
                      "items": {
                        "type": "number"
                      }
                    }
                  ],
                  "description": "Approximate tick count, the exact tick values, or \"ends\" for the first and last label only."
                },
                "grid": {
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "enum": [
                        "solid",
                        "dashed",
                        "dotted"
                      ]
                    }
                  ],
                  "description": "Grid lines from this axis."
                },
                "labels": {
                  "type": "boolean",
                  "default": true,
                  "description": "Show tick labels."
                },
                "position": {
                  "enum": [
                    "top",
                    "bottom",
                    "left",
                    "right"
                  ],
                  "description": "Axis side. Defaults: x bottom, y left, y2 right. A side perpendicular to the axis maps onto the nearer end."
                },
                "titlePosition": {
                  "enum": ["start", "center", "end"],
                  "description": "Where the title sits along the axis. start is the minimum end (left or bottom). end is the maximum end. Default center."
                },
                "titleRotate": {
                  "type": "number",
                  "minimum": -360,
                  "maximum": 360,
                  "description": "Axis title rotation in degrees. Default 0 on x, -90 on a left y axis, and 90 on a right y or y2 axis."
                },
                "autoSkip": {
                  "type": "boolean",
                  "description": "Skip tick labels that would overlap. false draws every label. When omitted, crowded category labels still tilt about -40 degrees if that fits, and numeric ticks skip only when they collide."
                },
                "labelWidth": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 240,
                  "description": "Maximum tick-label width in pixels. Longer labels wrap, then ellipsize."
                },
                "labelLines": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 6,
                  "description": "Maximum lines for a wrapped tick label. Enables wrapping at 72 pixels when labelWidth is omitted."
                },
                "line": {
                  "description": "Axis baseline. Off unless set. Color defaults to the axis token.",
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "show": {
                          "type": "boolean",
                          "description": "Draw the baseline."
                        },
                        "color": {
                          "type": "string",
                          "description": "Stroke color. Defaults to the axis token."
                        },
                        "width": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 8,
                          "description": "Stroke width in pixels."
                        },
                        "dash": {
                          "enum": ["solid", "dashed", "dotted"],
                          "description": "Stroke pattern."
                        }
                      }
                    }
                  ]
                },
                "tickMarks": {
                  "enum": ["inside", "outside", "none"],
                  "description": "Tick marks at labeled ticks. none is the default. inside points into the plot."
                },
                "tickLength": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 24,
                  "description": "Tick mark length in pixels. Setting it draws outside marks unless tickMarks says otherwise."
                },
                "rotate": {
                  "type": "number",
                  "description": "Tick label rotation in degrees. When omitted, crowded category labels rotate about -40 degrees unless autoSkip is true."
                },
                "offset": {
                  "type": "number",
                  "minimum": -80,
                  "maximum": 80,
                  "description": "Shift the baseline outward in pixels. Positive moves it away from the plot."
                },
                "crosses": {
                  "type": "number",
                  "description": "Data value where this axis crosses the other. 0 draws the axis through zero."
                },
                "minorTicks": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 8,
                  "description": "Minor tick marks between major ticks. 0 hides them."
                },
                "breaks": {
                  "type": "array",
                  "maxItems": 3,
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["from", "to"],
                    "properties": {
                      "from": { "type": "number", "description": "Start of the collapsed range, in data units." },
                      "to": { "type": "number", "description": "End of the collapsed range, in data units." },
                      "share": { "type": "number", "minimum": 0.15, "maximum": 0.7, "description": "Fraction of the axis from zero to this break when the segment below crosses zero; otherwise the fraction for that whole segment. Default 0.4." }
                    }
                  },
                  "description": "Ranges collapsed to a short gap. The break mark is drawn on the axis. When the segment below crosses zero, share is the fraction of the axis from zero to the break (default 0.4); otherwise share is the fraction for that whole segment. Ticks inside a break are omitted. The axis line stops at the top tick."
                },
                "bands": {
                  "type": "array",
                  "items": { "$ref": "#/$defs/axisBand" },
                  "description": "Shaded y ranges, such as a target zone."
                }
              },
              "description": "Axis settings."
            }
          ],
          "description": "Axis options. Set to false to hide the axis."
        },
        "y2": {
          "oneOf": [
            {
              "type": "boolean",
              "description": "false hides the axis; true uses defaults."
            },
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Axis title. Defaults to the channel title (none for time axes)."
                },
                "format": {
                  "$ref": "#/$defs/format",
                  "description": "Tick label format. Defaults to the channel format. On a strip this formats the ticks only. The row end label uses mark.labelFormat."
                },
                "ticks": {
                  "oneOf": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 50
                    },
                    {
                      "const": "ends",
                      "description": "Label only the first and last tick."
                    },
                    {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 50,
                      "items": {
                        "type": "number"
                      }
                    }
                  ],
                  "description": "Approximate tick count, the exact tick values, or \"ends\" for the first and last label only."
                },
                "grid": {
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "enum": [
                        "solid",
                        "dashed",
                        "dotted"
                      ]
                    }
                  ],
                  "description": "Grid lines from this axis."
                },
                "labels": {
                  "type": "boolean",
                  "default": true,
                  "description": "Show tick labels."
                },
                "position": {
                  "enum": [
                    "top",
                    "bottom",
                    "left",
                    "right"
                  ],
                  "description": "Axis side. Defaults: x bottom, y left, y2 right. A side perpendicular to the axis maps onto the nearer end."
                },
                "titlePosition": {
                  "enum": ["start", "center", "end"],
                  "description": "Where the title sits along the axis. start is the minimum end (left or bottom). end is the maximum end. Default center."
                },
                "titleRotate": {
                  "type": "number",
                  "minimum": -360,
                  "maximum": 360,
                  "description": "Axis title rotation in degrees. Default 0 on x, -90 on a left y axis, and 90 on a right y or y2 axis."
                },
                "autoSkip": {
                  "type": "boolean",
                  "description": "Skip tick labels that would overlap. false draws every label. When omitted, crowded category labels still tilt about -40 degrees if that fits, and numeric ticks skip only when they collide."
                },
                "labelWidth": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 240,
                  "description": "Maximum tick-label width in pixels. Longer labels wrap, then ellipsize."
                },
                "labelLines": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 6,
                  "description": "Maximum lines for a wrapped tick label. Enables wrapping at 72 pixels when labelWidth is omitted."
                },
                "line": {
                  "description": "Axis baseline. Off unless set. Color defaults to the axis token.",
                  "oneOf": [
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "show": {
                          "type": "boolean",
                          "description": "Draw the baseline."
                        },
                        "color": {
                          "type": "string",
                          "description": "Stroke color. Defaults to the axis token."
                        },
                        "width": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 8,
                          "description": "Stroke width in pixels."
                        },
                        "dash": {
                          "enum": ["solid", "dashed", "dotted"],
                          "description": "Stroke pattern."
                        }
                      }
                    }
                  ]
                },
                "tickMarks": {
                  "enum": ["inside", "outside", "none"],
                  "description": "Tick marks at labeled ticks. none is the default. inside points into the plot."
                },
                "tickLength": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 24,
                  "description": "Tick mark length in pixels. Setting it draws outside marks unless tickMarks says otherwise."
                },
                "rotate": {
                  "type": "number",
                  "description": "Tick label rotation in degrees. When omitted, crowded category labels rotate about -40 degrees unless autoSkip is true."
                },
                "offset": {
                  "type": "number",
                  "minimum": -80,
                  "maximum": 80,
                  "description": "Shift the baseline outward in pixels. Positive moves it away from the plot."
                },
                "crosses": {
                  "type": "number",
                  "description": "Data value where this axis crosses the other. 0 draws the axis through zero."
                },
                "minorTicks": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 8,
                  "description": "Minor tick marks between major ticks. 0 hides them."
                },
                "breaks": {
                  "type": "array",
                  "maxItems": 3,
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["from", "to"],
                    "properties": {
                      "from": { "type": "number", "description": "Start of the collapsed range, in data units." },
                      "to": { "type": "number", "description": "End of the collapsed range, in data units." },
                      "share": { "type": "number", "minimum": 0.15, "maximum": 0.7, "description": "Fraction of the axis from zero to this break when the segment below crosses zero; otherwise the fraction for that whole segment. Default 0.4." }
                    }
                  },
                  "description": "Ranges collapsed to a short gap. The break mark is drawn on the axis. When the segment below crosses zero, share is the fraction of the axis from zero to the break (default 0.4); otherwise share is the fraction for that whole segment. Ticks inside a break are omitted. The axis line stops at the top tick."
                },
                "bands": {
                  "type": "array",
                  "items": { "$ref": "#/$defs/axisBand" },
                  "description": "Shaded ranges on the second y axis."
                }
              },
              "description": "Axis settings."
            }
          ],
          "description": "Second (right) y axis, used by y series with axis 'y2'."
        }
      },
      "description": "Axis display. Scale domains live on encoding.<channel>.scale; this block is display-only."
    },
    "legend": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "show": {
              "type": "boolean",
              "description": "Show the legend."
            },
            "position": {
              "enum": ["top", "right", "bottom", "left", "inside"],
              "default": "top",
              "description": "Placement. inside draws over the plot; pair it with anchor."
            },
            "anchor": {
              "enum": ["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"],
              "description": "Anchor for an inside legend. Setting anchor without position uses inside."
            },
            "align": {
              "enum": ["start", "center", "end"],
              "description": "Alignment of items within the legend block."
            },
            "orient": {
              "enum": ["horizontal", "vertical"],
              "description": "Item flow. Default horizontal on the top and bottom, vertical on the sides."
            },
            "maxRows": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum visible rows. Further rows page behind the first, with previous and next controls."
            },
            "title": {
              "type": "string",
              "description": "Legend title."
            },
            "hide": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Series names omitted from the legend. The series still draws."
            },
            "symbol": {
              "enum": ["circle", "square", "diamond", "triangle", "line", "cross"],
              "description": "Marker used for every series unless symbols overrides it."
            },
            "symbols": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "series": { "type": "string", "description": "Series name." },
                  "symbol": {
                    "enum": ["circle", "square", "diamond", "triangle", "line", "cross"],
                    "description": "Marker for that series."
                  }
                }
              },
              "description": "Per-series legend markers."
            },
            "interactive": {
              "type": "boolean",
              "default": false,
              "description": "Click a legend item to hide/show its series. Off unless set; the SVG records it as data-ck-intent."
            },
            "values": {
              "type": "boolean",
              "default": false,
              "description": "Show each series' value (last, or slice value for donut) next to its name."
            }
          },
          "description": "Legend settings."
        }
      ],
      "description": "Legend. true/false or settings. Default: shown when there is more than one series (or for donut)."
    },
    "tooltip": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "show": {
              "type": "boolean",
              "description": "Show the tooltip."
            },
            "mode": {
              "enum": [
                "index",
                "nearest"
              ],
              "default": "index",
              "description": "'index' shows all series at the hovered x; 'nearest' shows the closest point only."
            },
            "crosshair": {
              "type": "boolean",
              "default": true,
              "description": "Draw a vertical guide line at the hovered x."
            },
            "crosshairLabel": {
              "type": "boolean",
              "default": false,
              "description": "Print the hovered x value on the guide."
            },
            "position": {
              "enum": [
                "auto",
                "top",
                "bottom",
                "left",
                "right"
              ],
              "default": "auto",
              "description": "Where the card sits. auto tries above, then below, then beside the point."
            },
            "background": {
              "type": "string",
              "description": "Tooltip card fill. A CSS colour. The page reads it from the chart."
            },
            "radius": {
              "type": "number",
              "minimum": 0,
              "maximum": 24,
              "description": "Tooltip corner radius in px."
            },
            "shadow": {
              "type": "string",
              "description": "Tooltip box-shadow. A CSS shadow value."
            },
            "crosshairColor": {
              "type": "string",
              "description": "Crosshair stroke. A CSS colour."
            },
            "fields": {
              "type": "array",
              "items": {
                "oneOf": [
                  {
                    "$ref": "#/$defs/fieldName"
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "field"
                    ],
                    "properties": {
                      "field": {
                        "$ref": "#/$defs/fieldName"
                      },
                      "title": {
                        "type": "string",
                        "description": "Label shown."
                      },
                      "format": {
                        "$ref": "#/$defs/format"
                      },
                      "unit": {
                        "type": "string",
                        "description": "Unit printed after the value, such as cm or kWh."
                      }
                    },
                    "description": "Field with label/format."
                  }
                ]
              },
              "description": "Fields to show, in this order. Omit to keep the encoded series. Strings are field names."
            },
            "template": {
              "type": "string",
              "description": "Row template. Tokens: {x}, {name}, {value}, {unit}, and data field names. One row per series."
            },
            "pin": {
              "type": "boolean",
              "default": false,
              "description": "Tap to pin the tooltip. A second tap or Escape clears it. Pointer leave does not."
            },
            "hit": {
              "type": "number",
              "minimum": 8,
              "maximum": 48,
              "description": "Hit radius in pixels. Larger targets help a finger. Pinning uses 18 when hit is omitted."
            }
          },
          "description": "Tooltip settings."
        }
      ],
      "description": "Hover tooltip. true/false or settings. Default on for interactive charts."
    },
    "axisBand": {
      "type": "object",
      "additionalProperties": false,
      "required": ["from", "to"],
      "properties": {
        "from": {
          "type": ["number", "string"],
          "description": "Start of the range, in data units or a category."
        },
        "to": {
          "type": ["number", "string"],
          "description": "End of the range, in data units or a category."
        },
        "label": {
          "type": "string",
          "description": "Text shown on the band."
        },
        "color": { "$ref": "#/$defs/color" },
        "opacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.12,
          "description": "Fill opacity, 0–1."
        }
      },
      "description": "A shaded range on an axis."
    },
    "stripEnd": {
      "type": "object",
      "additionalProperties": false,
      "required": ["group", "at"],
      "properties": {
        "group": {
          "type": "string",
          "description": "Group value, the same string the row uses."
        },
        "at": {
          "enum": ["summary", "min", "max", "mean"],
          "description": "Which statistic the bracket end sits on. summary is the tick that is drawn, or the median when the tick is hidden."
        }
      },
      "description": "One end of a strip compare bracket."
    },
    "annotation": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type",
            "axis",
            "value"
          ],
          "properties": {
            "type": {
              "const": "rule"
            },
            "axis": {
              "enum": [
                "x",
                "y",
                "y2"
              ],
              "description": "Axis the value is on."
            },
            "value": {
              "type": [
                "number",
                "string"
              ],
              "description": "Position in data units (number, or date/category string on x)."
            },
            "dash": {
              "enum": [
                "solid",
                "dashed",
                "dotted"
              ],
              "default": "dashed",
              "description": "Line style."
            },
            "labelPosition": {
              "enum": [
                "start",
                "center",
                "end"
              ],
              "default": "end",
              "description": "Where along the line the label sits."
            },
            "label": {
              "type": "string",
              "description": "Text shown with the annotation."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": {
              "$ref": "#/$defs/color"
            }
          },
          "description": "Rule: a line at a value (target, threshold, deploy time)."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type",
            "axis",
            "from",
            "to"
          ],
          "properties": {
            "type": {
              "const": "band"
            },
            "axis": {
              "enum": [
                "x",
                "y",
                "y2"
              ],
              "description": "Axis the range is on."
            },
            "from": {
              "type": [
                "number",
                "string"
              ],
              "description": "Start of range."
            },
            "to": {
              "type": [
                "number",
                "string"
              ],
              "description": "End of range."
            },
            "opacity": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "default": 0.12,
              "description": "Fill opacity 0–1."
            },
            "label": {
              "type": "string",
              "description": "Text shown with the annotation."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": {
              "$ref": "#/$defs/color"
            }
          },
          "description": "Band: a shaded range between two values."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type",
            "x",
            "label"
          ],
          "properties": {
            "type": {
              "const": "text"
            },
            "x": {
              "type": [
                "number",
                "string"
              ],
              "description": "x position in data units."
            },
            "y": {
              "type": "number",
              "description": "y position in data units. Omit to pin to the top of the plot."
            },
            "label": {
              "type": "string",
              "description": "Text shown with the annotation."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": {
              "$ref": "#/$defs/color"
            }
          },
          "description": "Text: a note pinned to a data coordinate."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "method"],
          "properties": {
            "type": { "const": "trendline" },
            "method": {
              "enum": ["mean", "median", "linear"],
              "description": "mean and median are horizontal lines. linear is a least-squares fit."
            },
            "axis": {
              "enum": ["y", "y2"],
              "default": "y",
              "description": "Series axis the statistic is taken from."
            },
            "series": {
              "type": "string",
              "description": "Series name. Defaults to the first series on the axis."
            },
            "dash": {
              "enum": ["solid", "dashed", "dotted"],
              "default": "dashed",
              "description": "Line style. Mean and median default to dashed; linear defaults to solid."
            },
            "label": {
              "type": "string",
              "description": "Text at the end of the line. Defaults to Mean, Median, or Linear."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": { "$ref": "#/$defs/color" }
          },
          "description": "Trendline: mean, median, or a linear fit, with a label."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "method"],
          "properties": {
            "type": { "const": "regression" },
            "method": {
              "enum": ["linear", "loess"],
              "default": "linear",
              "description": "linear is least squares. loess is a local weighted fit."
            },
            "band": {
              "type": "boolean",
              "default": false,
              "description": "Shade a 95% confidence band around the fit."
            },
            "bandwidth": {
              "type": "number",
              "minimum": 0.2,
              "maximum": 1,
              "default": 0.6,
              "description": "Loess window as a fraction of the points. Ignored for linear."
            },
            "axis": {
              "enum": ["y", "y2"],
              "default": "y",
              "description": "Series axis the fit is taken from."
            },
            "series": {
              "type": "string",
              "description": "Series name. Defaults to the first series on the axis."
            },
            "label": {
              "type": "string",
              "description": "Text at the end of the fit. Defaults to Linear fit or Loess."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": { "$ref": "#/$defs/color" }
          },
          "description": "Regression overlay: a linear or loess fit, with an optional confidence band. Not a separate chart type."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "x", "label"],
          "properties": {
            "type": { "const": "marker" },
            "x": {
              "type": ["number", "string"],
              "description": "x position in data units, or a category."
            },
            "y": {
              "type": "number",
              "description": "y position in data units. Omit to use the series value at x."
            },
            "label": {
              "type": "string",
              "description": "Text in the callout box."
            },
            "dx": {
              "type": "number",
              "description": "Horizontal offset of the text box, in pixels."
            },
            "dy": {
              "type": "number",
              "description": "Vertical offset of the text box, in pixels. Negative is up."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": { "$ref": "#/$defs/color" }
          },
          "description": "Callout: a point, a leader, and a text box kept inside the plot."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "from", "to", "label"],
          "properties": {
            "type": { "const": "compare" },
            "from": { "$ref": "#/$defs/stripEnd" },
            "to": { "$ref": "#/$defs/stripEnd" },
            "label": {
              "type": "string",
              "description": "Text on the bracket."
            },
            "z": {
              "type": "number",
              "minimum": -20,
              "maximum": 20,
              "description": "Draw order. Higher paints later. Negative paints under the marks."
            },
            "color": { "$ref": "#/$defs/color" }
          },
          "description": "Strip only: a bracket from one group's summary, min, max, or mean to another's. Other chart types warn CK3093."
        }
      ],
      "description": "A reference mark drawn on the chart."
    },
    "theme": {
      "oneOf": [
        {
          "enum": [
            "auto",
            "soft",
            "refined",
            "editorial",
            "midnight",
            "emerald",
            "mono",
            "slate",
            "arctic",
            "orchid",
            "obsidian",
            "neon",
            "mocha",
            "owl",
            "retro",
            "copper",
            "rose",
            "sunset",
            "silver",
            "pearl",
            "latte",
            "tape",
            "kite",
            "mustard",
            "violet"
          ],
          "description": "Preset name. 'auto' and 'soft' are the Soft default (light-dark, transparent plot). 'refined' and 'editorial' are built in. 'midnight' is opt-in. tape, kite, mustard, and violet ship with the other named presets and render as midnight until that preset is imported."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "preset": {
              "enum": [
                "auto",
                "soft",
                "refined",
                "editorial",
                "midnight",
                "emerald",
                "mono",
                "slate",
                "arctic",
                "orchid",
                "obsidian",
                "neon",
                "mocha",
                "owl",
                "retro",
                "copper",
                "rose",
                "sunset",
                "silver",
                "pearl",
                "latte",
                "tape",
                "kite",
                "mustard",
                "violet"
              ],
              "default": "auto",
              "description": "Base preset. tape, kite, mustard, and violet need @chartkitdev/core/themes/all or the matching themes entry."
            },
            "mode": {
              "enum": [
                "auto",
                "light",
                "dark"
              ],
              "default": "auto",
              "description": "Force light or dark, or follow prefers-color-scheme."
            },
            "brand": {
              "description": "Hex colour, or a list of up to eight. Shorthand #rgb and a missing hash are repaired to #rrggbb. render() derives light and dark tokens when @chartkitdev/core/themes/brand is imported. Until then the named preset is used.",
              "oneOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 32
                },
                {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 8,
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32
                  }
                }
              ]
            },
            "tokens": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "background": {
                  "type": "string",
                  "description": "Chart background. CSS value or var(--x)."
                },
                "surface": {
                  "type": "string",
                  "description": "Card/tooltip background. CSS value or var(--x)."
                },
                "text": {
                  "type": "string",
                  "description": "Primary text. CSS value or var(--x)."
                },
                "muted": {
                  "type": "string",
                  "description": "Secondary text, tick labels. CSS value or var(--x)."
                },
                "grid": {
                  "type": "string",
                  "description": "Grid lines. CSS value or var(--x)."
                },
                "axis": {
                  "type": "string",
                  "description": "Axis lines. CSS value or var(--x)."
                },
                "accent": {
                  "type": "string",
                  "description": "Highlight color (single-series default). CSS value or var(--x)."
                },
                "positive": {
                  "type": "string",
                  "description": "Good/up color (deltas, up candles). CSS value or var(--x)."
                },
                "negative": {
                  "type": "string",
                  "description": "Bad/down color. CSS value or var(--x)."
                },
                "fontFamily": {
                  "type": "string",
                  "description": "CSS font-family. Omitted, or inherit, uses the page font. A list such as Georgia, serif sets --ck-font-family. At most 80 characters. No double quotes, <, >, ;, {, }, or backslash. Invalid values are CK3086."
                },
                "fontSize": {
                  "type": "number",
                  "minimum": 6,
                  "maximum": 32,
                  "description": "Base font size in px."
                },
                "series": {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 24,
                  "items": {
                    "$ref": "#/$defs/color"
                  },
                  "description": "Categorical series palette in order. CSS colors or var(--x). Default: var(--ck-series-1..12) falling back to the preset."
                },
                "lines": {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 24,
                  "items": {
                    "$ref": "#/$defs/color"
                  },
                  "description": "Darker series ink, one per series colour, for thin strokes and strip labels. Omitted, labels use the series colour."
                }
              },
              "description": "Override individual tokens."
            }
          },
          "description": "Theme object."
        }
      ],
      "description": "Look and feel. A preset name, or an object combining a preset, a light/dark mode and token overrides. Every token is also read from CSS variables --ck-<token> (and --ck-series-N) on the container, so host design systems (e.g. shadcn --chart-1..5) can theme charts with no JS. Default 'auto' is Soft: light-dark colours, transparent plot. Set --ck-background for the optional #f5f5f7 card."
    },
    "size": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "width": {
          "oneOf": [
            {
              "type": "number",
              "minimum": 1
            },
            {
              "const": "auto"
            }
          ],
          "default": "auto",
          "description": "Width in px, or 'auto' to fill the container and follow resizes."
        },
        "height": {
          "oneOf": [
            {
              "type": "number",
              "minimum": 1
            },
            {
              "const": "auto"
            }
          ],
          "description": "Height in px, or 'auto' to derive from width × aspectRatio or the container height."
        },
        "aspectRatio": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "width / height, used when height is 'auto' (e.g. 1.777 for 16:9)."
        },
        "minHeight": {
          "type": "number",
          "minimum": 0,
          "description": "Minimum height in px when responsive."
        },
        "padding": {
          "oneOf": [
            {
              "type": "number",
              "minimum": 0
            },
            {
              "type": "object",
              "additionalProperties": false,
              "description": "Per-side padding in px; omitted sides stay automatic.",
              "properties": {
                "top": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Top padding in px."
                },
                "right": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Right padding in px."
                },
                "bottom": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Bottom padding in px."
                },
                "left": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Left padding in px."
                }
              }
            }
          ],
          "description": "Inner padding in px around the plot, a number or per-side object. Default: automatic from axis label sizes."
        }
      },
      "description": "Dimensions. Default: fill container width, height by type (line/bar 320px, sparkline 32px, gauge 160px)."
    },
    "layout": {
      "type": "object",
      "additionalProperties": false,
      "description": "Small multiples, a composed dashboard, breakpoint rules, and right-to-left layout. The same JSON draws on the server and in the browser. The arrange pass loads with @chartkitdev/core/all and /extra. createRenderer([line]) does not include it; call mountLayout from @chartkitdev/core/layout first.",
      "properties": {
        "direction": {
          "enum": ["ltr", "rtl"],
          "description": "rtl mirrors a categorical x axis, moves the y axis to the right, and right-aligns the title. The SVG sets dir=rtl. Default ltr."
        },
        "coordinate": {
          "enum": ["cartesian", "polar"],
          "description": "Coordinate system. polar is angle and radius, and it is how radial-bar and rose draw. Setting polar on bar repairs the type to radial-bar. On pie or donut it repairs to rose. On any other type the patch removes it (CK3077). cartesian on radial-bar or rose warns CK3078 and the patch sets polar."
        },
        "facet": {
          "type": "object",
          "additionalProperties": false,
          "description": "One panel per value of field. columns and rows set the grid. wrap (default true) flows extra panels onto new rows. scales shared uses one y domain; independent lets each panel scale itself. legend shared draws one legend for the grid.",
          "properties": {
            "field": {
              "type": "string",
              "description": "Column that splits the data. A name that is not a field warns CK3041. Omitting it warns CK3040."
            },
            "columns": {
              "type": "integer",
              "description": "Panels across. 1 to 12. Outside that range warns CK3042 and the patch clamps it. Omit to choose from the category count."
            },
            "rows": {
              "type": "integer",
              "description": "Panels down. 1 to 12. Outside that range warns CK3043 and the patch clamps it."
            },
            "wrap": {
              "type": "boolean",
              "description": "Flow extra categories onto new rows. false keeps the grid and warns CK3049 when categories do not fit."
            },
            "scales": {
              "enum": ["shared", "independent"],
              "description": "shared (default) locks every panel to one nice y domain that includes the data max. Y labels and the y title sit on the outer column only, and x labels and the x title sit on the bottom row. independent scales each panel to its own data and repeats the axes."
            },
            "legend": {
              "enum": ["shared", "each"],
              "description": "shared (default) draws one legend under the grid. each repeats the legend in every panel."
            }
          }
        },
        "concat": {
          "type": "object",
          "additionalProperties": false,
          "description": "Several charts in one spec. views are chart specs. direction is vertical (default) or horizontal. columns wraps them into a grid; a view may set span to cover more than one column. When views has a chart, the outer spec may omit type, data, encoding, and metric. Setting this beside facet warns CK3048.",
          "properties": {
            "columns": {
              "type": "integer",
              "minimum": 1,
              "maximum": 4,
              "description": "Wrap views into this many columns, 2 to 4. A view may set span to the number of columns it covers, so one wide chart can sit above two narrower ones. Omit to use direction."
            },
            "direction": {
              "enum": ["vertical", "horizontal"],
              "description": "vertical stacks the views. horizontal places them in a row. Ignored when columns is set."
            },
            "gap": {
              "type": "number",
              "description": "Space between views, in px. Default 16."
            },
            "views": {
              "type": "array",
              "items": { "type": "object" },
              "description": "Chart specs. A view with no type warns CK3045. An empty list warns CK3044."
            }
          }
        },
        "breakpoints": {
          "type": "array",
          "description": "The first rule whose width matches size.width, or the container width when width is auto, overrides the layout. A non-positive maxWidth warns CK3046. columns or rows without a facet field warns CK3047.",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "maxWidth": {
                "type": "number",
                "description": "Match when the chart width is this many px or less."
              },
              "minWidth": {
                "type": "number",
                "description": "Match when the chart width is this many px or more."
              },
              "legend": {
                "type": "boolean",
                "description": "Show or hide the legend at this width."
              },
              "direction": {
                "enum": ["ltr", "rtl"],
                "description": "Text and axis direction at this width."
              },
              "columns": {
                "type": "integer",
                "description": "Facet columns at this width."
              },
              "rows": {
                "type": "integer",
                "description": "Facet rows at this width."
              },
              "wrap": {
                "type": "boolean",
                "description": "Facet wrap at this width."
              },
              "scales": {
                "enum": ["shared", "independent"],
                "description": "Facet scale mode at this width."
              },
              "facetLegend": {
                "enum": ["shared", "each"],
                "description": "Facet legend mode at this width."
              },
              "concatDirection": {
                "enum": ["vertical", "horizontal"],
                "description": "Concat direction at this width."
              }
            }
          }
        }
      }
    },
    "interaction": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "hover": {
          "type": "boolean",
          "default": true,
          "description": "Highlight hovered marks and drive the tooltip."
        },
        "select": {
          "enum": [
            "none",
            "point",
            "series"
          ],
          "default": "none",
          "description": "Click selection. 'point' or 'series'. Shift, Ctrl, or Meta adds another. Escape or a background click clears. Selected marks use --ck-selected; others use --ck-dim. Emits pointclick or seriesclick, and selectionchange."
        },
        "zoom": {
          "enum": [
            "none",
            "x",
            "xy"
          ],
          "description": "Wheel/pinch zoom. Default 'x' for candlestick, otherwise 'none'."
        },
        "pan": {
          "type": "boolean",
          "description": "Drag to pan when zoomed."
        },
        "brush": {
          "enum": [
            "none",
            "x"
          ],
          "default": "none",
          "description": "Drag to select a range, emitted as 'rangechange'."
        },
        "initialRange": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": [
              "number",
              "string"
            ]
          },
          "description": "Initially visible x range [from, to] in data units (zoomable charts)."
        },
        "export": {
          "type": "array",
          "items": { "enum": ["png", "svg", "csv"] },
          "description": "Formats offered by the export menu. The SVG records them as data-ck-export. The menu loads only when this list is set. toPNG, toSVG, and toCSV are @chartkitdev/core/export."
        },
        "navigator": {
          "description": "Overview sparkline and range slider under the chart. true, or an object with height. The slider loads with the interaction extras. The server SVG records data-ck-nav and does not include the control.",
          "oneOf": [
            { "type": "boolean" },
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "height": {
                  "type": "integer",
                  "description": "Overview height in px. 28 to 96. A value outside that range warns CK3035 and the patch clamps it."
                }
              }
            }
          ]
        },
        "sync": {
          "type": "string",
          "description": "Group id. Charts with the same id share the crosshair, tooltip, and x window, matched on the x value. An empty string warns CK3036."
        },
        "drilldown": {
          "type": "object",
          "additionalProperties": false,
          "description": "Click a bar, slice, or node to swap in a child spec. Children are JSON specs keyed by category. The server SVG lists the keys and does not include the breadcrumb.",
          "properties": {
            "key": {
              "type": "string",
              "description": "Data field that names the child. Default: encoding.x. A name that is not a field warns CK3039."
            },
            "children": {
              "type": "object",
              "additionalProperties": { "type": "object" },
              "description": "Child specs keyed by category. Each child needs a type. An empty map warns CK3037. A child with no type warns CK3038."
            }
          }
        }
      },
      "description": "What the user can do. Adapters emit events (pointclick, legendtoggle, rangechange) for app code; JSON never contains functions. navigator, sync, and drilldown are JSON too."
    },
    "animation": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "duration": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5000,
              "default": 400,
              "description": "Milliseconds."
            },
            "easing": {
              "enum": [
                "linear",
                "ease-out",
                "ease-in-out",
                "spring"
              ],
              "default": "ease-out",
              "description": "Easing curve."
            }
          },
          "description": "Animation settings."
        }
      ],
      "description": "Entry/update animation. Always disabled when the user prefers reduced motion."
    },
    "motion": {
      "description": "BETA. The API may change. How an update moves marks from the previous spec. Omitted and \"none\" are off, including every existing spec. \"auto\" is 320ms ease-out (cubic-bezier(0, 0, 0.58, 1)). An object sets duration in milliseconds, clamped to 0–800; 0 is off. Easing stays ease-out. render() and export ignore this field and return the settled SVG, so SSR and PNG/SVG export stay still. prefers-reduced-motion snaps. Morphs stop above 2,000 rows. A sliding window of a canvas line strokes in place and does not morph.",
      "oneOf": [
        {
          "enum": ["auto", "none"]
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "duration": {
              "type": "number",
              "minimum": 0,
              "maximum": 800,
              "description": "Milliseconds. Clamped to 0–800. 0 is off. Omitted means 320."
            }
          },
          "description": "BETA. Duration override. The API may change."
        }
      ]
    },
    "a11y": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "alt"
      ],
      "properties": {
        "alt": {
          "type": "string",
          "minLength": 10,
          "maxLength": 500,
          "description": "Short text alternative with the key insight, e.g. 'Revenue rose 18% from Jan to Jun 2026, peaking in May.'"
        },
        "description": {
          "type": "string",
          "description": "Longer description (methodology, caveats). Exposed via aria-describedby."
        },
        "keyboard": {
          "type": "boolean",
          "default": true,
          "description": "Arrow-key navigation between points and series with announcements. On by default when an adapter mounts the chart on the client; set false to turn the keys off and keep the chart SVG out of the tab order. A static render() string is not affected. Types with no keyboard model yet ignore the default."
        },
        "dataTable": {
          "type": "boolean",
          "default": true,
          "description": "A data table for screen readers, visually hidden, capped at 1000 evenly spaced rows. On by default when an adapter mounts the chart on the client; set false to leave it out. true also adds a visible 'Show data table' button. A static render() string is not affected."
        }
      },
      "description": "Accessibility. 'alt' is required: a one or two sentence description of what the chart shows and its key takeaway, used as the accessible name/description and for text-only renders (agents should always write it)."
    }
  }
}
