Specification

A Vega specification defines an interactive visualization in JavaScript Object Notation (JSON).

Below is a basic outline of a Vega specification. Complete specifications include definitions for an appropriate subset of the data, scales, axes, marks, etc. properties.

{
  "$schema": "https://vega.github.io/schema/vega/v3.0.json",
  "description": "A specification outline example.",
  "width": 500,
  "height": 200,
  "padding": 5,
  "autosize": "pad",

  "signals": [],
  "data": [],
  "scales": [],
  "projections": [],
  "axes": [],
  "legends": [],
  "marks": []
}

Top-Level Specification Properties

Property Type Description
$schema URL The URL for the Vega schema.
description String A text description of the visualization.
background Color The background color of the entire view (defaults to transparent).
width Number The width in pixels of the data rectangle.
height Number The height in pixels of the data rectangle.
padding Number | Object The padding in pixels to add around the visualization. If a number, specifies padding for all sides. If an object, the value should have the format {"left": 5, "top": 5, "right": 5, "bottom": 5}. Padding is applied after autosize layout completes.
autosize String | Autosize Sets how the visualization size should be determined. If a string, should be one of pad (default), fit or none. Object values can additionally specify parameters for content sizing and automatic resizing. See the autosize section below for more.
config Config Configuration settings with default values for marks, axes and legends.
signals Signal[ ] Signals are dynamic variables that parameterize a visualization.
data Data[ ] Data set definitions and transforms define the data to load and how to process it.
scales Scale[ ] Scales map data values (numbers, dates, categories, etc) to visual values (pixels, colors, sizes).
projections Projection[ ] Cartographic projections map (longitude, latitude) pairs to projected (x, y) coordinates.
axes Axis[ ] Coordinate axes visualize spatial scale mappings.
legends Legend[ ] Legends visualize scale mappings for visual values such as color, shape and size.
title Title Title text to describe a visualization.
marks Mark[ ] Graphical marks visually encode data using geometric primitives such as rectangles, lines, and plotting symbols.
encode Encode Encoding directives for the visual properties of the top-level group mark representing a chart’s data rectangle. For example, this can be used to set a background fill color for the plotting area, rather than the entire view.

Autosize

Vega views can be sized (and resized) in various ways. If an object, the value should have the format {"type": "pad", "resize": true}, where type is one of the autosize strings and resize is a boolean indicating if autosize layout should be re-calculated on every update.

Name Type Description
type String Required. The sizing format type. One of "pad" (default), "fit" or "none". See the autosize types documentation for descriptions of each.
resize Boolean A boolean flag indicating if autosize layout should be re-calculated on every view update. The default (false) causes layout to be perform once upon initialization and then kept stable. To externally force a resize, use the View.resize API method.
contains String Determines how size calculation should be performed, one of content (default) or padding. The default setting (content) inteprets the width and height settings as the data rectangle (plotting) dimensions, to which padding is then added. In contrast, the padding setting includes the padding within the view size calculations, such that the width and height settings indicate the total intended size of the view.

Autosize Types

The total size of a Vega visualization may be determined by multiple factors: specified width, height, and padding values, as well as content such as axes, legends, and titles. The support different use cases, Vega provides three different autosize types for determining the final size of a visualization view:

  • none: No automatic sizing is performed. The total visualization size is determined solely by the provided width, height and padding values. For example, by default the total width is calculated as width + padding.left + padding.right. Any content lying outside this region will be clipped. If autosize.contains is set to "padding", the total width is instead simply width.
  • pad: Automatically increase the size of the view such that all visualization content is visible. This is the default autosize setting, and ensures that axes, legends and other items outside the normal width and height are included. The total size will often exceed the specified width, height, and padding.
  • fit: Automatically adjust the layout in an attempt to force the total visualization size to fit within the given width, height and padding values. This setting causes the plotting region to be made smaller in order to accommodate axes, legends and titles. As a result, the value of the width and height signals may be changed to modify the layout. Though effective for many plots, the fit method can not always ensure that all content remains visible. For example, if the axes and legends alone require more space than the specified width and height, some of the content will be clipped. Similar to none, by default the total width will be width + padding.left + padding.right, relative to the original, unmodified width value. If autosize.contains is set to "padding", the total width will instead be the original width.