VSON Markup Reference

Document Structure

Every VSON document is a JSON object with the following structure:

{
  "Version": "<String>",
  "Template": "<String>",
  "McpGenerated": "<Boolean>",
  "KeepDocument": "<Boolean>",
  "Shape": "<Shape Object>",
  "Title": "<TitleShape Object>",
  "Returns": "<Array of Return Object>",
  "Colors": "<Array of ColorEntry Object>",
  "Symbols": "<Array of SymbolEntry Object>",
  "DataTable": "<Array of DataTableDefinition Object>"
}

Floor plans use a different document structure. See Floor Plans.

Units and Formats

• All measurements are in 1/100 inches unless otherwise specified. A 2-inch-wide shape has "MinWidth": 200.
• Text sizes are in points.
• Colors are hex RGB values (#FFFFFF or #FFFFFFAA) or aliases from the Colors array.
• Dates use YYYY-MM-DD format. Times use HH-MM-SS format.
• Array indices for tables are 1-based (the first row or column is 1).
• Floor plans use architectural notation strings ("12'", "5' 6\\""), never decimals. See Floor Plans.

Defaults

• Shape: MinWidth 180, MinHeight 80 (1.8" x 0.8").
• Text: TextSize 12, TextFont Arial, TextAlignH "center", TextAlignV "middle".
• Shape IDs: Unique positive integers starting at 1, assigned sequentially.
• ShapeContainer spacing: 50 (0.5") between shapes and around the container border.
• Cell shape margin: 20 (0.2").
• Floor plan wall thickness: "4\\""

BACK TO TOP

Floor Plans

Floor plans use the "Floorplan" template and a different document structure than diagrams. They do not use Shape.ID, Shape.Label, ShapeList, Returns, or Colors. Instead, they describe rooms as outlines (closed polygons of walls), features on walls (doors, windows, gaps), and furniture inside or outside of rooms and the outline.

Floor Plan Document Structure

{
  "Version": "1.0",
  "Template": "Floorplan",
  "FloorplanSettings": {
    "scaletype": "Architectural",
    "thickness": "4\""
  },
  "Symbols": [],
  "Shape": {
    "Hide": true,
    "Outline": []
  }
}

• Shape.Hide is always true on floor plans.
• FloorplanSettings.scaleType is "Architectural" for imperial, "Metric" for metric.
• FloorplanSettings.thickness is the default

Measurements

Floor plans use architectural notation strings when in architectural scale, and decimal or pixels when in metric or pixel scaletype.

If scaletype is set to architectural then decimal input will be converted before use: 16.9' becomes 16' 11" (fractional foot X 12, rounded).

Outline Object

One outline per room (or per building footprint). The document's shape Shape.Outline array holds all outlines.

{
  "origin": { "x": "8'", "y": "4'" },
  "thickness": "4\"",
  "segments": [],
  "furniture": []
}

Segment Object

Each segment runs from the previous segment's endpoint (or the origin, for the first segment) to its own endPoint. Endpoints are relative to the outline origin, not absolute. A segment is defined entirely by its endpoint coordinates — there is no required tracing direction (clockwise and counter-clockwise are equally valid), and diagonal walls (endpoints that change both x and y) are supported.

{
  "endPoint": { "x": "12'", "y": "0'" },
  "features": [
    { "start": "4'", "length": "4'", "GUID": "532349ab-8678-4a49-b6b4-ea613e895678" }
  ]
}

Closure is optional. An outline whose last endpoint returns to {"x": "0'", "y": "0'"} in local coordinates forms a closed room. Outlines may also remain open: a one or two-segment run is a half-wall or a wall stub, and an open multi-segment run is a partition. When generating a room, close the outline (at least 3 segments, ending at the local origin, with ∑+x = ∑-x and ∑+y = ∑-y; when representing partial walls, leave it open.

Negative endpoint coordinates are valid and expected when the outline's origin sits on a corner other than the top-left.

Feature Object

Doors, windows, and gaps placed along a wall segment.

{
  "start": "2' 7 1/2\"",
  "length": "4' 6\"",
  "GUID": "532349ab-8678-4a49-b6b4-ea613e895678",
  "name": "Window"
}

Every feature must resolve one of two ways: an inline GUID, or a name that is mapped in the Symbols array. If both are provided, the GUID wins. Never provide "GUID":null or "GUID":"".

Constraint: start + length must not exceed the segment length.

Furniture Object

Furniture defined with an outline. Items are usually placed inside the outline, but placement outside it is valid too — useful for exterior features like patio plants or outdoor lighting.

{
  "position": { "x": "8' 6\"", "y": "4' 10\"" },
  "dimensions": { "width": "4'", "height": "5' 6\"" },
  "rotation": 0,
  "GUID": "c3861822-49a3-442a-8be4-e614a61046d2",
  "name": "Bed"
}

Resolution works exactly as for features: inline GUID, or name mapped in Symbols; GUID wins when both are present.

Standard GUID Symbols

The top-level Symbols array is a mapping between names and symbol GUIDs, declared as { "Name":..., "ID":<GUID> }. Its purpose is to avoid repeating GUIDs throughout the document: once a mapping is declared, features and furniture may reference the symbol by name alone. Inline GUID references are always valid, with or without a corresponding Symbols entry. Every Symbols entry must carry a valid ID — an entry without a GUID maps nothing.

Common floor plan symbol GUIDs (any of SmartDraw's symbols may be used; copy other GUIDs from the editor via right-click → "Copy Symbol ID"):

Shared Walls

When two rooms share a wall, the matching segments of the two outlines must coincide exactly in document coordinates: same length, same orientation. SmartDraw renders the shared segment as one wall when the coordinates match. Plan each room's absolute position first, then set its origin, so adjacent rooms line up along the common wall.

Floor Plan Validation Checklist

Format requirements (violations make a document invalid):

• JSON parses without errors.
• Template is "Floorplan" and FloorplanSettings has scaletype and thickness.
• Every feature and furniture item resolves to a symbol: an inline GUID, or a name mapped in the Symbols array. No "GUID": null or "GUID": "".
• Every Symbols entry has a valid ID.
• start + length ≤ segment length for every feature.
• All measurements use the units set by scaletype.

Recommended for generated room plans (ok to break these rules, but usually causes a defect in a generated floor plan):

• Room outlines close: final endpoint , , , at least 3 segments. (Open outlines are legal — they are half-walls or partitions, not rooms.)
• Features on each segment listed in ascending start order.
• Furniture intended for a room stays inside that room's walls. (Furniture outside outlines is legal for exterior items.)
• Shared walls coincide exactly between adjacent outlines — never two parallel walls a few inches apart.
• At least one exterior door exists.

Complete Floor Plan Example

{
  "Version": "1.0",
  "Template": "Floorplan",
  "FloorplanSettings": {
    "scaletype": "Architectural",
    "thickness": "4\""
  },
  "Symbols": [
    { "Name": "Window", "ID": "532349ab-8678-4a49-b6b4-ea613e895678" },
    { "Name": "Door",   "ID": "a653e73a-ba92-43a1-9030-21b86b23b888" },
    { "Name": "Bed",    "ID": "c3861822-49a3-442a-8be4-e614a61046d2" }
  ],
  "Shape": {
    "Hide": true,
    "Outline": [{
      "origin": { "x": "8'", "y": "4'" },
      "thickness": "4\"",
      "segments": [
        {
          "endPoint": { "x": "12'", "y": "0'" },
          "features": [
            { "start": "4'", "length": "4'", "GUID": "532349ab-8678-4a49-b6b4-ea613e895678" }
          ]
        },
        { "endPoint": { "x": "12'", "y": "14'" } },
        {
          "endPoint": { "x": "0'", "y": "14'" },
          "features": [
            { "start": "4' 6\"", "length": "3'", "GUID": "a653e73a-ba92-43a1-9030-21b86b23b888" }
          ]
        },
        { "endPoint": { "x": "0'", "y": "0'" } }
      ],
      "furniture": [
        {
          "position": { "x": "2' 9\"", "y": "2' 6\"" },
          "dimensions": { "width": "6' 6\"", "height": "7'" },
          "rotation": 0,
          "GUID": "c3861822-49a3-442a-8be4-e614a61046d2"
        }
      ]
    }]
  }
}

A 12' x 14' bedroom with a window on the top wall, a door on the bottom wall, and a king bed against the back wall. Note the bed's position is in absolute document coordinates (outline origin 8' plus a 2' 9" room-relative offset).

SmartDraw Floor Plan Notation, the field-friendly text format for capturing measurements, converts directly to this structure. See the SmartDraw Floor Plan Notation Reference.

BACK TO TOP

Shape Object

The building block of every diagram. A shape carries a label, formatting, the connectors that attach its children, and optional features like tables, images, timelines, and shape data.

{
  "ID": "<Number>",
  "Label": "<String>",
  "ShapeType": "<String>",
  "TextBold": "<Boolean>",
  "TextItalic": "<Boolean>",
  "TextUnderline": "<Boolean>",
  "TextSize": "<Number>",
  "TextFont": "<String>",
  "TextMargin": "<Number>",
  "TextColor": "<String>",
  "FillColor": "<String>",
  "TextAlignH": "<String>",
  "TextAlignV": "<String>",
  "TextGrow": "<String>",
  "MinWidth": "<Number>",
  "MinHeight": "<Number>",
  "LineThick": "<Number>",
  "LineColor": "<String>",
  "LineLabel": "<String>",
  "LinePattern": "<String>",
  "Hide": "<Boolean>",
  "Truncate": "<Number>",
  "ShapeConnectorType": "<String>",
  "Note": "<String>",
  "NoteIcon": "<String>",
  "ShapeList": "<Array of ShapeConnector Objects>",
  "Hyperlink": "<Hyperlink Object>",
  "TextHyperlink": "<Hyperlink Object>",
  "Table": "<Table Object>",
  "Image": "<Image Object>",
  "ShapeContainer": "<ShapeContainer Object>",
  "Data": "<DataTableShapeEntry Object>",
  "Timeline": "<Timeline Object>",
  "Gantt": "<Gantt Object>",
  "Gauge": "<Gauge Object>",
  "ExpandedView": "<Document Object>"
}

A shape may contain at most one of Table, Timeline, Gantt, or Gauge.

ShapeConnector Object

Defines an automatic connector with child shapes. Each entry in a shape's ShapeList array is a shape connector. A connector can attach one or more child shapes to a parent; a parent can have multiple entries in its ShapeList (typically one per direction), and each connector's Shapes array can contain many shapes that all flow in that direction.

{
  "Collapse": "<Boolean>",
  "Direction": "<String>",
  "FillColor": "<String>",
  "LineThick": "<Number>",
  "LineColor": "<String>",
  "LinePattern": "<String>",
  "Arrangement": "<String>",
  "Shapes": "<Array of Shape Object>",
  "ShapeConnectorType": "<String>",
  "StartArrow": "<Number>",
  "EndArrow": "<Number>",
  "TextBold": "<Boolean>",
  "TextItalic": "<Boolean>",
  "TextUnderline": "<Boolean>",
  "TextSize": "<Number>",
  "TextFont": "<String>",
  "LineLabel": "<String>",
  "DefaultShape": "<Shape Object>"
}

Connector Behavior by Diagram Type

• Flowcharts. Any shape can have multiple ShapeList entries in any direction. Two or more entries in the same direction render as a split path. All shapes flowing in the same direction belong in a single connector's Shapes array.
• Org charts. Each shape may have one ShapeList entry. The direction of the root shape's connector sets the direction of the whole tree (default "Bottom"); direction on non-root shapes is ignored.
• Mind maps. The root shape may have two ShapeList entries, one "Left" and one "Right".
• Trees, hierarchies, decision trees. One ShapeList entry per shape. Multiple entries on a tree shape are consolidated into one.

BACK TO TOP

ShapeContainer Object

Places child shapes inside a parent shape with no connecting lines. Containers are recursive: shapes in a container can themselves contain containers, connectors, or tables.

{
  "Shapes": "<Array of Shape Object>",
  "Arrangement": "<String>",
  "Wrap": "<Number>",
  "VerticalSpacing": "<Number>",
  "HorizontalSpacing": "<Number>",
  "ShapesAlignH": "<String>",
  "ShapesAlignV": "<String>",
  "Hide": "<Boolean>",
  "DefaultShape": "<Shape Object>"
  
}

The parent shape sizes itself to fit its children. Parents of a ShapeContainer are transparent by default unless FillColor is set.

BACK TO TOP

Return Object

A segmented line connecting any two shapes by ID: cross-links, back-edges, loop-backs, dotted-line relationships. Returns live in the document root's Returns array.

{
  "StartID": "<Number>",
  "EndID": "<Number>",
  "StartDirection": "<String>",
  "EndDirection": "<String>",
  "LinePattern": "<String>",
  "Label": "<String>",
  "StartArrow": "<Number>",
  "EndArrow": "<Number>",
  "LineThick": "<Number>",
  "LineColor": "<String>",
  "Curved": "<Boolean>",
  "LineType": "<String>",
  "BehindID": "<Number>"
}

BACK TO TOP

Table Object

Inserts a table object into a shape. Cells behave like shapes: they can hold labels, colors, images, hyperlinks, and even complete nested shapes.

{
  "Rows": "<Number>",
  "Columns": "<Number>",
  "ColumnWidth": "<Number>",
  "RowHeight": "<Number>",
  "Cell": "<Array of Cell Object>",
  "AlternateRows": "<TableAlternateRowsColors Object>",
  "Join": "<Array of Join Object>",
  "ColumnProperties": "<Array of ColumnProperties Object>",
  "RowProperties": "<Array of RowProperties Object>",
  "ShapeMarginH": "<Number>",
  "ShapeMarginV": "<Number>"
}

Cell Object

{
  "Column": "<Number>",
  "Row": "<Number>",
  "Label": "<String>",
  "TextSize": "<Number>",
  "TextBold": "<Boolean>",
  "TextItalic": "<Boolean>",
  "TextUnderline": "<Boolean>",
  "TextFont": "<String>",
  "TextColor": "<String>",
  "FillColor": "<String>",
  "TextAlignH": "<String>",
  "TextAlignV": "<String>",
  "Truncate": "<Number>",
  "Note": "<String>",
  "NoteIcon": "<String>",
  "Hyperlink": "<Hyperlink Object>",
  "TextHyperlink": "<Hyperlink Object>",
  "Image": "<Image Object>",
  "Shape": "<Shape Object>",
  "ExpandedView": "<Document>",
  "UseTextRectAsFrame": "<Boolean>"
}

Row and Column are required and 1-indexed. A cell can hold one Shape, which may itself be the root of an entire nested structure (container, connector tree, or another table); the cell grows to fit. UseTextRectAsFrame: true constrains an image to the cell's inset text rectangle.

Join Object

{ "Row": 1, "Column": 1, "N": 3, "Down": false }

Merges N cells starting at the 1-indexed anchor cell. Down: true joins downward; the default joins rightward.

ColumnProperties and RowProperties

{ "Index": 1, "LineThick": "<Number>", "LineColor": "<String>", "LinePattern": "<String>", "Width": "<Number>", "FixedWidth": false }

{ "Index": 1, "LineThick": "<Number>", "LineColor": "<String>", "LinePattern": "<String>", "Height": "<Number>", "FixedHeight": false }

Index is 1-based. Line settings style the grid lines of that column or row; Width and Height set minimum dimensions in 1/100". Cell-level properties may also be applied to a whole row or column. RowProperties are applied before ColumnProperties; individual Cell settings override both.

TableAlternateRowsColors

{ "Color1": "<String>", "Color2": "<String>" }

BACK TO TOP

TitleShape Object

A title centered 1/2" above the diagram.

{
  "Label": "<String>",
  "TextBold": false,
  "TextItalic": false,
  "TextUnderline": false,
  "TextSize": 16,
  "TextFont": "<String>",
  "TextColor": "<String>"
}

BACK TO TOP

Timeline Object

Renders a timeline inside a shape. A shape with a Timeline cannot also contain a Table.

{
  "Arrangement": "<String>",
  "Auto": "<Boolean>",
  "HideGridLabelColumn": "<Boolean>",
  "Start": "<String>",
  "Starttime": "<String>",
  "Length": "<Number>",
  "EventType": "<String>",
  "Position": "<String>",
  "LineLength": "<Number>",
  "DefaultShape": "<Shape Object>",
  "Rows": "<Array of Row objects>",
  "Events": "<Array of Event objects>"
}

Timeline Row

{ "Label": "<String>", "RowType": "<String>" }

A RowType of label-row spans the full timeline as a section title; normal rows carry events.

Event Object

An event object inherits all Shape properties (label, colors, fonts, tables) plus:

BACK TO TOP

Gantt Object

Renders a Gantt chart inside a shape. A shape with a Gantt cannot also contain a Table, Gauge, or Timeline.

{
  "Projectname": "<String>",
  "UseDataTable": "<DataTable Object>",
  "GanttColumns": "<Array of GanttColumn objects>",
  "GanttOptions": "<GanttOptions object>"
}

Gantt Tasks

Each row of UseDataTable.Rows is one task, expressed as a Fields array of {Name, Value} pairs. Valid field names (from GanttChartColumnNames):

GanttColumn

{ "Name": "<String>", "Settings": { "Title": "<String>", "Width": "<Number>" } }

Controls which columns appear, their titles, and widths. Renameable columns: Task, Person, Department, Cost, Custom.

GanttOptions

{ "AllWorkingDays": false, "Holidays": "<String>" }

AllWorkingDays: true counts every day; otherwise weekends are skipped. Holidays is one of the following: "None", "USA", "UK", "Australia", "Canada".

The Gantt chart inherits the fill color, line properties, and text properties of its containing shape.

BACK TO TOP

Gauge Object

Renders a gauge inside a shape. Gauges show a value between a minimum and maximum. A shape with a Gauge cannot also contain a Table, Timeline, or Gantt. The minimum gauge size is 2x2 inches.

{
  "GaugeType": "<String>",
  "Settings": "<Array of value objects>",
  "ShowDataTable": "<Boolean>"
}

Settings is an array of {"Name": "<String>", "Value": "<String>"} pairs whose valid names depend on the GaugeType. For the fully documented RadialDetail:

The gauge will inherit the fill color, line properties, and text color of its containing shape. ShowDataTable: true renders an accompanying shape data table in the SmartDraw editor.

BACK TO TOP

Shape Data Objects

Shape data attaches structured records to shapes, displayed as a tooltip on an "i" icon.

DataTableDefinition

Declared in the document root's DataTable array.

{
  "ID": "<String>",
  "TableName": "<String>",
  "Columns": "<Array of DataTableColumn Object>",
  "Rows": "<Array of DataTableRow Object>"
}

DataTableColumn

{ "Name": "<String>", "Type": "<String>" }

Type is one of the following: "String", "Int", "Float", "Bool", "Date".

DataTableRow and DataTableField

{ "RowID": 1, "Fields": [ { "Name": "<String>", "Value": "<String>" } ] }

DataTableShapeEntry

Attached to a shape via Shape.Data. References a table by TableID and a row by RowID; if TableID is omitted, the document's first table is used. Values may also be supplied inline via Fields.

{
  "RowID": 1,
  "TableID": "<String>",
  "Fields": "<Array of DataTableField Object>"
}

BACK TO TOP

Supporting Objects

Hyperlink

{ "url": "<String>" }

On Shape.Hyperlink or Cell.Hyperlink, places a hyperlink icon in the bottom right. On TextHyperlink, makes the label itself a clickable link with blue underline styling.

Image

{ "url": "<String>" }

Displays the image inside the shape or cell, scaled to preserve aspect ratio.

ColorEntry

{ "Name": "<String>", "Value": "<String>" }

Value is #RRGGBB or #RRGGBBAA. The Name can then be used anywhere a color string is accepted.

SymbolEntry

{ "Name": "<String>", "ID": "<String>" }

Assigns an alias to a SmartDraw symbol GUID. The alias can then be used as a ShapeType value. Any of the 34,000+ SmartDraw symbols can be used; the symbol's GUID is available from the right-click menu in the SmartDraw interface. For floor plans, Symbols entries must always carry a valid GUID (See Floor Plans).

ExpandedView

A complete VSON Document object attached to a Shape, Cell, task, or event. Rendered as a drill-down tooltip on the parent. Expanded views nest recursively.

BACK TO TOP

Enumerations

VSTemplates

ShapeTypes

Symbol aliases defined in the Symbols array are also valid ShapeType values.

ShapeConnectorTypes

ShapeConnectorArrangement

ShapeContainerArrangement

Directions

"Left", "Right", "Top", "Bottom".

LinePatterns

"Solid", "Dotted", "Dashed".

HorizontalAlignments

"left", "center", "right".

VerticalAlignments

"top", "middle", "bottom".

TextGrow

Arrowheads

TimelineArrangements

TimelineEventTypes

GanttChartColumnNames

"Row", "Task", "Start", "Length", "End", "Parent", "Master", "Person", "PercentComplete", "Department", "Cost", "Custom".

GanttChartHolidays

"None", "USA", "UK", "Australia", "Canada".

DataTableDataTypes

"String", "Int", "Float", "Bool", "Date".

BACK TO TOP