Vithanco
Home / 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 defines a notation schema inline in a VGL file, with no Swift changes. Everything a built-in notation provides — node types, edge types, layout direction — can be expressed this way.

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

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

A vgraph then references it by name exactly like a built-in notation. vnotation blocks must appear before any vgraph or metagraph that references them, which allows single-pass parsing.

backgroundColor: is the fill. color: is accepted as an older spelling of it on input, but backgroundColor is what a document exports — the same name a node instance stores it under, so the two surfaces agree.

nodeStyle: — required on every node type

The parser treats the value as an opaque string; the semantic layer validates it against this table.

nodeStyle: Additional parameters Description
iconWithText backgroundColor: (required), icon:, iconColor: (default white), iconSize: (default 24) Icon above text, coloured background
simpleRoundedText backgroundColor: Text in a rounded rectangle
roundedBox backgroundColor: Plain rounded box
withCategory backgroundColor:, category: (short header label) Box with a coloured category bar on top
withCategoryAndIcon backgroundColor:, category:, icon:, iconColor:, iconSize: Category bar plus icon
iconOnly icon:, iconColor: (default black), iconSize: Icon without text
circle backgroundColor: Circular node
bareText — Plain text, no decoration
hidden — Not rendered
custom — Falls back to bareText; reserved for future style expressions

extends

Adds every node and edge type from a built-in notation, on top of which yours adds more:

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

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

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

A complete example

vnotation RiskMap {
    layout: topToBottom

    node type: Risk    [nodeStyle: iconWithText, backgroundColor: "#cc3333", icon: "exclamationmark.triangle"]
    node type: Control [nodeStyle: iconWithText, backgroundColor: "#339933", icon: "shield"]
    node type: Owner   [nodeStyle: circle,       backgroundColor: "#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
}

A vnotation can take extensions like any other notation:

vgraph sm1: SimpleMap, Annotation "Annotated Map" { … }.