Reference¶

Introduction¶

This document describes the Vega specification syntax. A Vega specification is a JSON-formatted structure that describes a visualization, which can be sent to the backend for rendering.

See the Tutorials for examples of how to use Vega.

Resources¶

Standards¶

The JavaScript Object Notation (JSON) Data Interchange Format

Vega Concepts¶

Specification Language Syntax¶

The Vega specification includes properties for describing the source data, mapping the data to the visualization area, and visual encoding:

Property	Type	Description
Width and Height Properties	`unsigned integer`	Visualization area width and height.
Data Property	`array`	Source data.
Scales Property	`array`	Data-to-visualization area mapping.
Marks Property	`array`	Geometric primitive used to visually encode data.

The root Vega specification has the following JSON structure:

{
  "width": <number>,
  "height": <number>,
  "data": [],
  "scales": [],
  "marks": []
}

Format rules¶

Property names are case-sensitive.
Property values are typed.
Unsupported properties are ignored by the rendering engine.

Width and Height Properties¶

Width and height properties give the width and height of the visualization area, in pixels. Both properties are required and must be positive, unsigned integers.

Example:

Set the viewing area width to 384 pixels and the height to 564 pixels.

vegaSpec = {
    width: 384,
    height: 564,
    data: [ ... elided ... ],
    scales: [ ... elided ... ],
    marks: [ ... elided ... ]
};

Data Property¶

The Vega data model uses tabular data, similar to a spreadsheet. The data are organized in rows with any number of named columns.

General data property JSON format:

"data": [
  {
    "name": <dataID>,
    "format": <datasourceFormat>,
    "sql": <dataSource>
  },
  {
     ...
  }
]

Use the data property to specify the visualization data sources by providing an array of one or more data definitions. A data definition must be an object identified by a unique name, which can be referenced in other areas of the specification. Data can be statically defined in-line or can reference columns from a database table using a SQL statement.

The data specification has the following properties:

Property Data Type Required Description

name string X User-assigned database table name.

format string How the data are parsed. polys is the only supported format.

Data Source

string

Data source:

values: Embedded, static data values defined in-line as JSON.

sql: A SQL query that loads the data.

Examples:

Load discrete x- and y column values using the values database table type.

vegaSpec = {
    width: 384,
    height: 564,
    data: [
        {
          name: "coordinates",
          values: [ {"x":0, "y":3}, {"x":1, "y":5} ],
    scales: [ ... elided ... ],
    marks: [ ... elided ... ]
};

Use the sql database table type to load latitude and longitude coordinates from the tweets_data database table.

vegaSpec = {
    width: 384,
    height: 564,
    data: [
        {
          name: "tweets",
          sql: "SELECT lon as x, lat as y FROM tweets_data WHERE (lon >= -32 AND lon < 66) AND (lat >= -45 AND lat < 68)"
        }
    ],
    scales: [ ... elided ... ],
    marks: [ ... elided ... ]
};

`name`¶

The name property uniquely identifies a data set, and is used for reference by other Vega properties, such as the Marks Property.

`format`¶

The format property specifies how the data are parsed. If not specified, data are assumed to be in row-oriented JSON format.

This property is required for Polys Type marks and the value must be polys.

Data Source¶

The database table source property key-value pair specifies the location of the data and implies how the data are loaded:

Key	Value	Description
`sql`	SQL statement	Data are loaded using a SQL statement.
`values`	JSON data	Data are loaded from static, key-value pair data definitions.

Scales Property¶

The scales property maps visually encoded data values to pixel positions with attributes, such as color. See the D3 scales documentation for additional background information about scales.

General scales property JSON format:

"scales": [
  {
    "name": <scaleID>,
    "type": <scaleType>,
    "domain": <inputValues>,
    "range": <outputValues"
    "default": <defaultOutputValue>,
    "nullValue": <nullDataValue>
  },
  {
     ...
  }
],

The scales specification is one or more arrays with the following properties:

Property Field	Data Type	Required	Description
name	string	X	User-defined scale name.
type	string		Scale type, which specifies the``domain``-to-`range` transform: `linear`: A quantitative, continuous scale that preserves proportion among data items. `log`: A quantitative scale that applies a logarithmic transform to the data. `ordinal`: A scale with discrete domain and range. `pow`: A quantitative scale that applies an exponential transform to the input data. `quantize`: A quantitative, discrete scale that divides input data into segments. `sqrt`: A quantitative scale that applies an square root transform to the input data.
domain	array		Domain. Array of input interval data values.
range	string or array		Range. Array of output interval visual data values.
default	number		Default output value to use when domain value does not map to range value.
nullValue	number		Output value to use when input value is `null`.

Example:

Define two scales, x and y. For the x scale, linearly transform input data values between -100 and 999 to the visualization area width. For the y scale, linearly transform input data values between 0 and 500 to the visualization area height. The width and height range values are pre-defined literals that reference the Width and Height Properties.

vegaSpec = {
    width: 384,
    height: 564,
    data: [ ... elided ... ],
    scales: [
        {
            name: "x",
            type: "linear",
            domain: [ -100, 999 ],
            range: "width"
        },
        {
            name: "y",
            type: "linear",
            domain: [ 0, 500 ],
            range: "height"
        }
    ],
    marks: [ ... elided ... ]
};

`name`¶

The name property uniquely identifies the scale for reference by other properties.

`type`¶

The type property specifies how to transform the input, domain data to output, range visual values. Vega supports the following transforms, categorized by quantitative, discrete, and discretizing scales:

Quantitative Scales¶

Type	Description	Additional Information
`linear`	Preserves proportional differences, where range value y can be expressed as a linear function of the domain value `x: y = mx + b`.	D3 linear scale
`log`	Applies a logarithmic transform to the input domain value before the output range value is computed. The mapping to the range value y can be expressed as a logarithmic function of the domain value x: `y = m log(x) + b`. As `log(0) = -∞`, a log scale domain must be strictly-positive or strictly-negative. The domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values. A log scale with a negative domain has a well-defined behavior for negative values. For a negative domain, input and output values are implicitly multiplied by `-1`. The behavior of the scale is undefined if you compute a negative value for a log scale with a positive domain, and vice versa. `log` scale values must be positive. Default = base `10`.	D3 logarithmic scale
`pow`	Applies an exponential transform to the input domain value before the output range value is computed. Range value y can be expressed as a polynomial function of the domain value x: `y = mx^k + b`, where `k` is the exponent. Power scales also support negative domain values, and input value and resulting output value are then multiplied by -1. Default exponent = `1`.	D3 power scale
`sqrt`	A shorthand for power scales with an exponent of 0.5, indicating a square root transform. `sqrt` scale values must be positive.	D3 sqrt scale

Discrete Scales¶

Type Description Resource

ordinal

Applies a discrete domain-to-range transform, and functions as a lookup table from a domain value to a range value.

Specify a default value for domain values that do not map to a range.

D3 ordinal scale

Discretizing Scales¶

Type	Description	Resource
`quantize`	Divides input domain values into uniform segments based on the number of values in, or the cardinality of, the output range, where range value y can be expressed as a quantized linear function of the domain value x: `y = m round(x) + b.`	D3 quantize scale

`domain`¶

The domain field specifies the domain of input data values. For quantitative data, this can take the form of a two-element array.

Example:

Specify minimum and maximum input values.

domain: [ -100, 999 ]

For ordinal or categorical data, the domain can be an array of valid input values.

Example:

Specify valid input data languages.

"domain": ["en",  "es", "fr"]

The domain can be specified as a reference to a data source.

Example:

Derive a scale domain from the value field of data objects in the table database table source. If the scale type is a quantize, the derived domain is a two-element [min, max] array. If the scale type is ordinal, the derived domain is an array of all distinct values.

"domain": {"data": "table", "field": "value"}

Scale domains can also be derived using values from multiple fields. Multiple fields from the same data set can be specified by replacing the field property with a fields property that takes an array of field names.

Scale domains can also use values pulled from different data sets. In this case, the domain object must have a fields property, which is an array of basic data references.

Example:

"domain": {
  "fields": [
    {"data": "table1", "field": "price"},
    {"data": "table2", "field": "cost"}
   ]
}

`range`¶

Scale range specifies the set of visual values. For numeric values, the range can take the form of a two-element array with minimum and maximum values. For ordinal or quantized data, the range can be an array of desired output values, which are mapped to elements in the specified domain.

Scale ranges can be specified in the following ways:

As an array of static values: "range": [0, 500] or "range": ['a', 'b', 'c'].
For ordinal scales, as a data reference for a set of distinct field values: "range": {"data": "table", "field": "value"}.
Using pre-defined literals: "range": "width" or "range": "height".

Example:

Specify a color scale that quantizes input values between 0 and 100 among five visual output colors.

{
  name: "color",
  type: "quantize",
  domain: [ 0, 100 ],
  range: [ "#115f9a", "#1984c5", "#c9e52f", "#d0ee11", "#d0f400"
  ]
}

Scale ranges can accept width and height string literals that map to the Width and Height Properties.

Value	Description
`width`	A spatial range that is the value of t``width``.
`height`	A spatial range that is the value of `height`. The direction of the range, top-to-bottom or bottom-to-top, is determined by to the scale type.

Example:

Specify a y scale that linearly maps input values between 0 and 500 to the height of the visualization area.

{
    name: "y",
    type: "linear",
    domain: [ 0, 500 ],
    range: "height"
}

`default`¶

The default scales property specifies the output value to use when the input domain value does not map to the range.

`nullValue`¶

The nullValue scales property specifies the output value to use when the input value is null.

Marks Property¶

Marks visually encode data using geometric primitives.

General marks property JSON format:

"marks": [
  {
    "type": <marksType>,
    "from": { data: <dataSourceID> },
    "properties": { <propName>: <propVal> }, ... { <propName>: <propVal> }
  },
  {
     ...
  }
],

A marks specification includes the following properties:

Property	Data Type	Required	Description
type	string	X	Graphical marks type or shape.
from	object	(polys-only)	database table associated with the marks.
properties	object	X	Visual encoding rules. Valid properties depend on marks `type`.

Each marks property is associated with the specified Data Property.

Example:

Associate the points geometric primitive with tweets data items.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
            "name": "tweets",
            "sql": "SELECT  ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "points",
            "from": { data: "tweets" },
            "properties": { ... elided ... }
        },
        { ... elided ... }
    ]
};

The backend renders marks in marks property array order.

Marks property values can be constants or as data references. You can use the Scales Property to transform marks property values to the visualization area.

Example:

Apply the x and y scales to the x and y database table columns to scale the data to the visualization area width and height.

const exampleVega = {
  "width:" 384,
  "height:" 564,
  "data:" [ ... elided ... ],
  "scales:" [
    {
      "name:" "x",
      "type:" "linear",
      "domain:" [-3650484.1235206556,7413325.514451755],
      "range:" "width"
    },
    {
      "name:" "y",
      "type:" "linear",
      "domain:" [-5778161.9183506705, 10471808.487466192],
      "range:" "height"
    }
  ],
  "marks:" [
    {
      "type:" "points",
      "from:" { "data:" "tweets" },
      "properties:" {
        "x:" { "scale:" "x", "field:" "x" },
        "y:" { "scale:" "y","field:" "y"}
      }
    }
  ]
};

`type`¶

The marks property must include a type property that specifies the geometric primitive to use to render the data.

marks type	Description
`points`	Render marks as points. See Points Type.
`polys`	Render marks as a polygon. See Polys Type.
`symbol`	Render marks as a shape. See Symbol Type.

Points Type¶

The points marks type renders data as a point.

Vega supports the following points properties:

Property	Data Type	Description
`fillColor`	color	Fill color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.
`size`	number	Graphical primitive size, in pixels. Must be a scale/data reference or a number.
`x`	number	Primary x-coordinate, in pixels. Must be a scale/data reference or a number for `points`, or a scale/data reference for polys. See Value Reference.
`y`	number	Primary y-coordinate, in pixels. Must be a scale/data reference or a number for `points`, or a scale/data reference for polys. See Value Reference.
`z`	number	Primary depth-coordinate, in pixels. Must be a scale/data reference or a number for `points`. See Value Reference.

Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.

Polys Type¶

The polys type renders data as a polygon, and the data property from property must be set to polys.

Because the data format property is polys, the rendering engine assumes a polys database table layout and extracts the poly-related columns from the table. A polys database table layout implies that the first data column is the vertex x- and y-positions. The vertices are interleaved x and y values, such that vertex[0] = vert0.x, vertex[1] = vert0.y, vertex[2] = vert1.x, and vertex[3] = vert1.y, for example. The next three positions of a polys database table are the triangulated indices, and line loop and drawing information for unpacking multiple, associated polygons that can be packed as a single data item.

Vega supports the following polys properties:

Property	Data Type	Description
`fillColor`	color	Fill color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.
`lineJoin`	string	stroke line join method: `bevel` Extension of an endpoint. `miter` Clipped extension of an endpoint. `round` Semi-circle at an endpoint.
`miterLimit`	number	The miter limit at which to bevel a line join, in pixels. Must be a positive number. Default = `10.0`
`strokeColor`	color	Stroke color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference. Default color = `white`
`strokeWidth`	number	Stroke width, in pixels. Must be a scale/data reference or a number.
`x`	number	Primary x-coordinate, in pixels. Must be a scale/data reference or a number for `points`, or a scale/data reference for polys. See Value Reference.
`y`	number	Primary y-coordinate, in pixels. Must be a scale/data reference or a number for `points`, or a scale/data reference for polys. See Value Reference.

Example:

const exampleVega = {
  "width": 1004,
  "height": 336,
  "data": [
    {
      "name": "polys",
      "format": "polys",
      "sql": "SELECT ... elided ..."
    }
  ],
  "scales": [ ... elided ... ]
  "marks": [
    {
      "type": "polys",
      "from": {
        "data": "polys"
      },
      "properties": {
        "x": {
          "scale": "x",
          "field": "x"
        },
        "y": {
          "scale": "y",
          "field": "y"
        },
        "fillColor": {
          "scale": "polys_fillColor",
          "field": "avgContrib"
        },
        "strokeColor": "white",
        "strokeWidth": 0,
        "lineJoin": "miter",
        "miterLimit": 10
      }
    }
  ]
}

Symbol Type¶

The symbol marks type renders data as one of the following shapes:

Shape Literal	Description
`circle`	Circle
`cross`	Cross
`diamond`	Diamond
`hexagon-horiz`	Horizontal hexagon
`hexagon-vert`	Vertical hexagon
`square`	Square
`triangle-down`	Triangle pointing down
`triangle-left`	Triangle pointing left
`triangle-right`	Triangle pointing right
`triangle-up`	Triangle pointing up

Vega supports the following symbol properties:

Property	Data Type	Description
`fillColor`	color	Fill color. Must be a scale/data reference, a string, or a color represented by a 32-bit integer or unsigned integer. See Color Value Reference.
`stroke`	color	Stroke color.
`strokeCap`	string	Stroke cap for line ending style: `butt` (default) `round` `square`
`strokeJoin`	string	Stroke line join method: `miter` (default) `round` `bevel`
`strokeMiterLimit`	number	Miter limit at which to bevel a line join.
`strokeOpacity`	number	Stroke opacity: `0` = transparent `1` = opaque
`strokeWidth`	number	Stroke width, in pixels.
`x`	number	Primary x-coordinate, in pixels. Must be a scale/data reference or a number for `symbol`, or a scale/data reference for polys. See Value Reference.
`y`	number	Primary y-coordinate, in pixels. Must be a scale/data reference or a number for `symbol`, or a scale/data reference for polys. See Value Reference.
`z`	number	Primary depth-coordinate, in pixels. Must be a scale/data reference or a number for `symbol`. See Value Reference.

Specify x and y coordinate values using either constants or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be specified using constant values.

Example:

const exampleVega = {
  "width": 733,
  "height": 530,
  "data": [
    {
      "name": "heatmap_query",
      "sql": "SELECT ... elided ... "
    }
  ],
  "scales": [ ... elided ... ],
  ],
  "marks": [
    {
      "type": "symbol",
      "from": {
        "data": "heatmap_query"
      },
      "properties": {
        "shape": "square",
        "x": { "field": "x" },
        "y": { "field": "y" },
        "width": 1,
        "height": 1,
        "fillColor": { "scale": "heat_color", "field": "cnt" }
      }
    }
  ]
};

`from`¶

The from field specifies the input database table to use.

Data Source Field	Data Type	Description
`data`	string	Name of the data source. The `data` name must be defined in the Data Property. See Data Property.

Example:

Use the tweets database table for marks input data.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
          "name": "tweets",
          "sql": "SELECT ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "polys",
            "from": {"data": "tweets"},
            "properties": { ... elided ... }
        }
    ]
};

If from is not specified, the data source is implicitly a single point with the value defined in the points properties.

`properties`¶

The properties property specifies type-dependent visual encoding that define the position and appearance of mark instances.

Typically, a single mark instance is generated per input data element, except for polys, which use multiple data elements to represent a line or area shape.

The properties property defines visual encoding rules. The property value is specified using on e of the Value Reference options.

See the Points Type, Polys Type, and Symbol Type for a list of properties supported by each marks type.

Value Reference¶

A value reference describes how to specify marks properties values. The value can be a constant or data object reference:

Name	Type Description
`value`	Any	Constant value. If `field` is specified, `value` is ignored.
`field`	Field Reference	Perform a lookup on the current data value. The marks `from` property determines the source data table and the `field` name must be a column defined in the `data`. See Data Property.
`scale`	Field Reference	Name of a scale transform to apply to the mark. If the input is an object, it indicates a field value from which to dynamically look up the scale name and follows the Field Reference format. See Scales Property.

Examples:

Statically set the point fillColor and size.

"marks:" [
  {
    "type:" "points",
    "from:" {
      "data:" "tweets"
    },
    "properties:" {

         ... elided ...

      "fillColor": "blue",
      "size": 3
      }
    }
  }
]

For the x marks property, apply the x scale transform to the implicit x-coordinate data column.

"marks": [
  {
    "type": "polys",
    "from": {
      "data": "polys"
    },
    "properties": {
      "x": {
        "scale": "x",
        "field": "x"
      },

      ... elided ...

    }
  }
]

Field Reference¶

A field reference is either a string literal or an object. For object values, the following properties are supported:

Property	Type	Description
Property Name	FieldRef	Perform a lookup on the property name. This is the default operation when a field reference is a string.

Color Value Reference¶

Typically, color values are specified as a single RGB color value. To specify specific color fields or use a different color space, use one of the following color value reference formats:

Property Value Field Data Type Description

field string Name of the attribute from the data: sql field.

colorSpace

string

Space in which the color is defined:

Hue-Chroma-Luminance color space. See HCL color space.
- Use r, g, and b property names.
Hue, saturation, and lightness color space. See HSL and HSV color space.
- Use h, s, and l property names.
Lab color space. A perceptual color space with distances based on human color judgments. The L dimension represents luminance, the A dimension represents green-red opposition and the B dimension represents blue-yellow opposition. See Lab color space.
- Use l, a, and b property names.
RGB color space. A version of LAB, which uses polar coordinates for the AB plane. See RGB color space.
- Use h, c, and l property names.

Examples:

Set the red and blue channels of an RGB color as constants, and uses a scale transform to determine the green channel:

"fill": {
 "r": {"value": 255},
 "g": {"scale": "green", "field": "g"},
 "b": {"value": 0}
}

Use the rgb color space for the color field:

"fillColor": {
    "field": "color",
    "colorSpace": "rgb"
}

Reference¶

Introduction¶

Resources¶

Standards¶

Related Vega Implementations¶

Vega Concepts¶

Specification Language Syntax¶

Format rules¶

Width and Height Properties¶

Data Property¶

name¶

format¶

Data Source¶

Scales Property¶

name¶

type¶

Quantitative Scales¶

Discrete Scales¶

Discretizing Scales¶

domain¶

range¶

default¶

nullValue¶

Marks Property¶

type¶

Points Type¶

Polys Type¶

Symbol Type¶

from¶

properties¶

Value Reference¶

Field Reference¶

Color Value Reference¶

`name`¶

`format`¶

`name`¶

`type`¶

`domain`¶

`range`¶

`default`¶

`nullValue`¶

`type`¶

`from`¶

`properties`¶