This guide will walk you through everything you will want to know about VSON, its building blocks, and how to generate diagrams and floor plans automatically from data that show hierarchy, relationships, and physical space — such as flowcharts, org charts, timelines, gauges, floor plans, and more.
VSON is SmartDraw's JSON markup for describing diagrams and floor plans. You write a VSON document describing what you want, hand it to SmartDraw, and SmartDraw renders a perfectly formatted, fully editable drawing. There are no coordinates to compute, no shapes to position by hand. Just a description of the shapes and how they connect, or in the case of floor plans, the walls and what's inside them.
This simple VSON is rendered as an org chart:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
{
"Version": "1.0",
"Template": "OrgChart",
"McpGenerated": true,
"KeepDocument": true,
"Shape": {
"ID": 1,
"Label": "First Shape",
"ShapeConnector": [
{
"ShapeConnectorType": "OrgChart",
"Shapes": [
{ "ID": 2, "Label": "Second Shape" },
{ "ID": 3, "Label": "Third Shape" }
]
}
]
}
}
|
Just a few lines of markup create a perfectly formatted hierarchy of three shapes.
VSON is the markup language of SmartDraw's VisualScript engine, the intelligent formatting layer that positions every shape, draws every line, and chooses every spacing for you.
What makes VSON so easy is that you can take advantage of powerful intelligent formatting. To create a diagram using VSON, you don't have to use a coordinate system to describe the explicit placement of shapes. Instead you can leverage an intelligent rule-based formatting engine to simplify the format and reduce the work. VSON makes it easy to create a third-party tool, template, or AI integration that can quickly turn data and natural language into diagrams, automatically.
The following analogy is helpful in understanding the innovation that VSON represents.
We are all used to software that can take a set of XY data and plot a graph. Let's take for example a line graph made in Excel. To make the graph, you simply select two columns of data and request that Excel render a line graph. You don't specify the coordinates of each point on the line. You don't individually calculate the line between each point, or draw the axes separately, or define the pixels for numbers and text labels, and so forth. It would be no small feat to just draw a simple line graph if you had to calculate everything individually. Yet, about fifty years ago, that's exactly what you would have had to do to generate a graph on a computer using code. Today, we are completely used to the idea that to draw a graph, all we need to do is specify the type of graph we want and the data to plot and the software will draw it automatically.
But this has never been the case for diagrams until VSON.
In the very first VSON example we shared above, we specified that we wanted three shapes arranged in a hierarchy. The intelligent formatting engine did the rest.
Here's why VSON matters now: when you ask Claude, ChatGPT, or SmartDraw AI to "draw a flowchart of our hiring process", the AI doesn't draw the picture. It writes VSON, and SmartDraw renders it. VSON is the bridge between human intent and beautiful, fully editable SmartDraw drawings.
That means everything in this cookbook does double duty. Every recipe is a working VSON example you can adapt for your own tools and integrations, and it's reference material that teaches large language models how to produce valid SmartDraw drawings.
You can write VSON directly. You can let SmartDraw AI write it for you inside SmartDraw. You can connect Claude or ChatGPT to the SmartDraw MCP Server to render VSON from any AI workflow you build. The result is the same: a fully editable SmartDraw drawing.