Vega Reference Overview

A Vega specification is a JSON-formatted structure that describes a visualization, which can be sent to the back end for rendering. This document introduces the the Vega specification syntax and provides links to topics that provide more details about each Vega property.

For examples of using Vega, see Tutorials. You can also see and edit examples in Try Vega.

Specification Language Syntax

The Vega specification includes properties for describing the source data, mapping the data to the visualization area, and visual encoding. The root Vega specification supported by OmniSci has the following JSON structure and top-level properties:

{
  "width": <number>,
  "height": <number>,
  "data": [],
  "projections": [],
  "scales": [],
  "marks": []
}
Property Type Description
width and height unsigned integer Visualization area width and height, in pixels. Both properties are required.
Example: Set the viewing area width to 384 pixels and the height to 564 pixels: 
vegaSpec = {
    width: 384,
    height: 564,
    ...
};
data array Source data. The Vega data model uses tabular data, similar to a spreadsheet. Organized in rows with any number of named columns.
JSON format:
"data": [
  {
    "name": <dataID>,
    "format": <datasourceFormat>,
    "values": <valueSet> | "SQL": <dataSource> | "source": <dataSource> "transform": [ ... elided ... ]
  },
  {
     ...
  }
]
projections array Projection data. Maps longitude and latitude data to projected x and y coordinates.
JSON format: 
"projections": [
       {
         "name": "<projectionName>",
         "type": "<projectionType>",
         "bounds": {
               "x": [<minLong>,<maxLong>],
               "y": [<minLat>,<maxLat>]
         }
       }
]
scales array Data-to-visualization area mapping. Maps visually encoded data values to pixel positions with attributes, such as color.
JSON format: 
"scales": [
  {
    "name": <scaleID>,
    "type": <scaleType>,
    "domain": <inputValues>,
    "range": <outputValues>"
    "accumulator": <accumulatorType>
    "default": <defaultOutputValue>,
    "nullValue": <nullDataValue>
  },
  {
     ...
  }
]
marks array Geometric primitive used to visually encode data.
JSON format: 
"marks": [
  {
    "type": <marksType>,
    "from": { data: <dataSourceID> },
    "properties": { <propName>: <propVal> }, ... { <propName>: <propVal> }
    "transform": { <transformType>: <transformName> }
  },
  {
     ...
  }
]

Format Rules

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