The best Tools for Structured Visual Thinking VGL Guide — User-Defined Notations (`vnotation`)

VGL Guide — User-Defined Notations (`vnotation`)

Estimated reading time: 2 minutes.

User-Defined Notations (`vnotation`)

vnotation lets expert users define their own notation schema inline in a VGL file, without requiring any Swift code changes. Everything that built-in notations provide — node types, edge types, layout direction — can be expressed in VGL.

Basic Syntax

vnotation <Name> [extends <BuiltinNotation>] {
    layout: <topToBottom | leftToRight | rightToLeft | bottomToTop>

    node type: <TypeName>  [nodeStyle: <name>, color: "#hex", icon: "sf.symbol", ...]
    ...
    edge type: <edge_id>   from: <TypeName>  to: <TypeName>  [color: "#hex"]
    ...
}

A vgraph then references the vnotation by name, identically to any built-in notation:

vgraph <id>: <VnotationName> "<label>" [, Extension ...] {
    // identical syntax — node, edge, group, attribute overrides
}

File-Ordering Rule

vnotation blocks must appear before any vgraph that references them. This allows single-pass parsing and produces a clear error if violated.

`nodeStyle:` — Required on Every Node Type

nodeStyle: is required on every node type: declaration. The parser treats the value as an opaque string; the semantic layer validates it against the table below.

`nodeStyle:` value	Additional parameters	Description
`iconWithText`	`color:` (required), `icon:`, `iconColor:` (opt, default white), `iconSize:` (opt, default 24)	Icon above text, colored background
`simpleRoundedText`	`color:`	Text in a rounded rectangle
`roundedBox`	`color:`	Plain rounded box
`withCategory`	`color:`, `category:` (short header label)	Box with a colored category bar at top
`withCategoryAndIcon`	`color:`, `category:`, `icon:`, `iconColor:` (opt), `iconSize:` (opt)	Category bar + icon
`iconOnly`	`icon:`, `iconColor:` (opt, default black), `iconSize:` (opt)	Icon without text
`circle`	`color:`	Circular node
`bareText`	—	Plain text, no decoration
`hidden`	—	Node is not rendered
`custom`	—	Falls back to `bareText` in v1; reserved for future full style expressions

`extends` — Inheriting a Built-In Notation

The extends clause adds all node and edge types from a built-in notation, then your vnotation adds further types on top:

vnotation RichIBIS extends IBIS {
    node type: Stakeholder [nodeStyle: withCategory, color: "#884499", category: "S"]

    edge type: stakeholder_raises  from: Stakeholder to: Question
    edge type: stakeholder_answers from: Stakeholder to: Answer
}

v1 constraint: Only built-in notations can be extended. vnotation A extends B where B is itself a vnotation is not supported.

Examples

Pure vnotation — custom risk map:

vnotation RiskMap {
    layout: topToBottom

    node type: Risk    [nodeStyle: iconWithText, color: "#cc3333", icon: "exclamationmark.triangle"]
    node type: Control [nodeStyle: iconWithText, color: "#339933", icon: "shield"]
    node type: Owner   [nodeStyle: circle,       color: "#3366cc"]

    edge type: risk_has_control  from: Risk    to: Control
    edge type: control_owned_by  from: Control to: Owner
}

vgraph rm1: RiskMap "Project Risk Map" {
    node r1: Risk    "Schedule overrun"
    node c1: Control "Weekly reviews"
    node o1: Owner   "PM"
    edge r1 -> c1
    edge c1 -> o1
}

vnotation + Extension:

vnotation SimpleMap {
    node type: Concept [nodeStyle: simpleRoundedText, color: "#336699"]
    edge type: related  from: Concept to: Concept
}

vgraph sm1: SimpleMap, Annotation "Annotated Map" {
    node c1: Concept    "Main idea"
    node a1: Annotation "See also: section 3"
    edge c1 -> a1
}