Loading...
Deneb & Vega - 04: Skull of the Syntax

Deneb & Vega - 04: Skull of the Syntax

Share:

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:

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:

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:

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!

Previous post:

Deneb & Vega - 03: Start with the Canvas

Next post:

Deneb & Vega - 05: Get the Data