
Deneb & Vega - 04: Skull of the Syntax
30 Jun 2025
Introduction
Creating a chart with Vega can feel overwhelming, especially when the chart is complex or interactive. But if you understand the core components of Vega’s syntax, you can break down the process into small, manageable chunks—and that makes everything a lot easier. In this post, we’ll go over those core building blocks so you can start thinking in Vega terms.
Core Components
Data visualizations can involve many steps, but broadly speaking, the whole process can be divided into three main parts:
- Getting and preparing the data
- Indicating what we want to visualize
- Describing how we want to visualize it
As our charts get more advanced, we’ll need additional components, but these three are the essentials for getting something on the screen.
In the previous post, we talked about the canvas and how to create one. Once we have our canvas, the first thing we need is data. We use the data
block to bring in and prepare the data we want to visualize. This block is where you can import datasets, clean them up, and apply transformations.
Once the data is ready, we need to tell Vega what kind of data goes where. For example, in a column chart, we’ll usually have categories on the x-axis and numeric values on the y-axis. This kind of mapping is done using the scales
block.
Finally, we need to tell Vega how we want to visualize the data. Do we want a bar chart? A line? An area chart? A scatter plot? These visual elements are called marks, and they’re defined inside the marks
block.
So, the three components you absolutely need to get started are:
-
data
— what we’re visualizing -
scales
— how that data maps to the canvas -
marks
— what kind of visual elements we use to show the data
With just these three blocks, you can already get a chart on the canvas! It might not look very fancy, but it’s a great place to start. The basic structure with these components looks like this:
{
"$schema": "https://vega.github.io/schema/vega/v6.json",
"width": 500,
"height": 200,
"data": [ ],
"scales": [ ],
"marks": [ ]
}
Let’s look at a bar chart created using only these core components:
Other Components
As your visuals get more complex—or if you want to make them interactive—you’ll need to use a few more components. Here are the most common ones Vega offers:
-
signals
: This is where we define variables and parameters to make our visuals interactive. Think of it as adding logic to your visual. -
axes
: While thescales
block defines what kind of data goes where, theaxes
block tells Vega how to draw those axes—tick marks, labels, orientation, etc. -
legends
: No surprise here—this is where we customize the legend of our chart. -
projections
: If you’re creating a map, you’ll need this block to define how geographical data should be projected onto the canvas.
So, the top-level structure of a Vega spec with all these elements looks something like this:
{
"$schema": "https://vega.github.io/schema/vega/v6.json",
"width": 500,
"height": 200,
"data": [ ],
"signals": [ ],
"scales": [ ],
"projections": [ ],
"axes": [ ],
"legends": [ ],
"marks": [ ]
}
If you’re familiar with JSON
, you’ll notice that each of these blocks are defined as a
JSON array
A JSON array contains zero, one, or more ordered elements, separated by a comma. The JSON array is surrounded by square brackets [ ].
. That means we can include multiple datasets, multiple scales, multiple marks, and so on.
Why is that helpful? Hold your horses—we’ll explore that soon!