Skip to main content

D2 Tour

declarative diagramming header

D2 is a JSON/YAML-like language that stands for Declarative Diagramming. Declarative, as in, you write out what you want diagrammed, we generate it.

Our DSL is custom-made to integrate with the rest of Terrastruct’s unique features. You can define classes, tables, and code snippets, all in the same file. Of course, it also integrates with our mechanisms to handle complexity, allowing you to define layers and scenarios all through text.

declarative diagramming example

While Declarative Diagramming is a powerful feature, we don’t see it replacing the GUI. We love using the keyboard to fly through our machines, but sometimes a mouse is the more appropriate tool, like when we’re scrolling a website or pinching to zoom. Terrastruct is designed to give you the most optimized interface for diagramming, and that entails letting you switch between text editor and GUI seamlessly. The graphical interface, unlike lines of text, allows for easy scanning and quick visual feedback.

Our plan is to continue to leverage those advantages to give you the smoothest diagramming experience. For example, use your mouse to double click on a problem area, instead of searching hundreds of lines to find it. Choose a color interactively instead of typing the hex code. Click and drag a selection box to remove some deprecated entities instead of finding the exact lines they’re defined. It’ll all be bidirectional, so whatever you do on the GUI is reflected back into your declarations.

Declarative Diagramming is designed towards maximizing a single vector: reducing stress. Speed and maintainability are both highly prioritized, but our overarching goal is to turn diagramming into a pleasant experience. Plenty of tools can claim to do that for simple diagrams, but you stop having a good time as soon as you get to even slightly complex diagrams — the ones that most need to be drawn out.

Engineers are not visual designers, and the lack of ability to spatially architect a system should not block the creation of valuable documentation. Every drag and drop shouldn’t require planning, and updates shouldn’t be a frustrating exercise in moving things around and resizing to make room for the new piece. Declarative Diagramming removes all that friction.

Give the experience a try — you won’t want to go back.


We are deploying changes every day. Not everything described above may be available in the current version. See future plans.


The D2 language is experimental. Stability and backwards compatibility is not guranteed.