Deneb & Vega - 03: Start with the Canvas

Introduction

Now that we’re familiar with Vega, we can start building a logical understanding of its syntax. But before diving into the details, let’s take a step back and talk about something very basic—yet super important: the canvas.

What Is a Canvas?

If you’ve ever done any painting, you already know what a canvas is—it’s the surface where you paint your masterpiece. In Vega, the concept is pretty much the same. The canvas is where all the visual elements live.

The cool part? In Vega, you don’t need to explicitly create a canvas. Since Vega is just a structured JSON file, everything you write goes inside a pair of curly braces {}. These outermost braces automatically create a canvas for you.

So if you just type {} in the code editor, Vega technically creates a canvas. But—here’s the catch—you won’t see anything. Why? Because that canvas is 0 pixels wide and 0 pixels tall. It’s invisible.

Let’s Make It Visible

To actually see the canvas, we need to give it some dimensions. We can do that using the width and height properties. And to make things more obvious, let’s also give it a background color using the background property.

Here’s how that looks in Vega:

{
  "width": 250,
  "height": 100,
  "background": "grey"
}

And now, the result is something you can see—an actual grey canvas!

All the visual elements you create will be drawn inside this canvas. Think of it as the stage where your charts and marks perform.

We’ll talk about more customizations you can apply to the canvas later on. For now, let’s shift gears and look at something very helpful—the schema.

What Is a Schema?

By now, you know that Vega is a language that describes how visuals should look. Like any language, it has its own set of rules—a grammar, if you will. These rules are defined in what’s called a schema file.

When you include the schema in your code, the editor becomes smarter. It automatically checks your code for errors and highlights them right away. Super helpful!

You can include the schema using the $schema property at the top of your JSON:

{
  "$schema": "https://vega.github.io/schema/vega/v6.json",
  "width": 250,
  "height": 100,
  "background": "grey"
}

Technically, you can write Vega code without including the schema. In fact, we did that earlier just to display the canvas. But without the schema, you’ll probably end up spending hours debugging a missing comma or typo. Not fun at all!

So my advice? Always include the schema. It’s like having a grammar checker for your charts.