Vega-Lite Specification

Vega-Lite Specifications

At its core, Vega-Lite specifications are JSON objects that describe visualizations as mappings from data to properties of graphical marks (e.g., points or bars). By simply providing a mark type and a mapping, Vega-Lite automatically produces other visualization components including axes, legends, and scales. Unless explicitly specified, Vega-Lite determines properties of these components based on a set of carefully designed rules. This approach allows Vega-Lite specifications to be succinct and expressive, but also provide user control.

As it is designed for analysis, Vega-Lite also supports data transformation such as aggregation, binning, time unit conversion, filtering, and sorting. In addition, it also supports faceting a single plot into trellis plots or small multiples.

{
  "description": ... ,
  "data": ... ,
  "mark": ... ,
  "transform": ...,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      ...
    },
    "y": ...,
    "color": ...,
    ...
  },
  "config": ...
}

In Vega-Lite, a specification can have the following top-level properties.

Property Type Description
description String An optional description of this mark for commenting purpose. This property has no effect on the output visualization.
data Object An object describing the data source.
transform Object An object describing filter and new field calculation.
mark String The mark type. One of "bar", "circle", "square", "tick", "line", "area", "point", and "text".
encoding Object A key-value mapping between encoding channels and definition of fields.
config Object Configuration object.