Concepts

The document

Every VGL document declares a notation, which fixes the node and edge types available:

vgraph <graph_id>: <NOTATION> "<graph_label>" {
    ...
}

Nodes

node <id>: <NodeType> "<label>" [<attributes>];

The id must be unique in the document; the label and attributes are optional.

node q1: Question "What should we do?" [fontsize: 16; color: red];

Edges

edge <from_id> -> <to_id>: <EdgeType> "<label>" [<attributes>];

Both endpoints must be declared. Omit the edge type and VGL infers it from the node types, whenever that is unambiguous — which is most of the time, so most documents never name an edge type at all.

edge q1 -> a1: answered_by "Initial solution";
edge a1 -> pro1 [style: dashed];
edge q2 -> a2;                              // type inferred

Groups

Groups organise nodes hierarchically, nest to any depth, and may carry attributes. Edges may cross group boundaries freely.

group research "Research Phase" {
    style: filled;
    color: lightblue;

    node q1: Question "What to research?";
    node a1: Answer "User interviews";

    group methodology "Methods" {
        node m1: Pro "Direct feedback";
    };
};

Folded groups. Prefix a group with folded to render it collapsed into a single box. Folding auto-redirects any edges that crossed the boundary to the collapsed box, and the editor can fold and unfold in place.

folded group methodology "Methods" { … };

Typed groups (boundaries). A group can carry a type after its id, mirroring node typing — group <id>: <GroupType> "<label>" { … }. The type selects its appearance: a C4 SystemBoundary draws a dashed boundary when unfolded and its element card when folded. See C4.

Attributes

Inline in brackets, [a: 1; b: 2], or as bare statements inside a graph or group body.

Colouring one node. color sets a node's fill, overriding whatever its type says. fontColor sets the text on it; leave it out and the text is set to black or white for contrast, but only where it would otherwise stop being legible.

node epBackend: Container "Equipment Pooling Backend" [color: "#b6e6bd"];
node onApp: Container "ON App" [color: "#ffe08a"; fontColor: "#5c3d00"];

This is a per-node exception, not a second axis: the node keeps its type, so its shape, its stereotype line and every quality check still apply. Use it to mark what is new or changed in an otherwise ordinary diagram, and say what the colours mean somewhere the reader can see.

Every colour in VGL — a node's, an edge's, a group's, a graph's fontcolor — is a hex value or one of the 147 SVG colour keywords (red, cornflowerblue,

whitesmoke). Graphviz's larger X11 set is not accepted: chartreuse3 is an error, not a silent no-op. A name you write is kept as you wrote it when the document is exported; it is never derived back from a colour, since grey and gray are the same value.

Links

Any node, edge or group may carry a url pointing at whatever the element stands for — a ticket, a repository, a wiki page:

node q1: Question "Which datastore?" [url: "https://issues.example.com/ARCH-14"];

A linked element wears a small badge, clipped to its corner or sitting on the line for an edge. Clicking it follows the link in a new tab; hovering shows the destination first. The right-click menu carries Add URL… / Change URL…, Open URL and Remove URL.

Only http, https and mailto are accepted, and anything without a scheme is read as https://. Other schemes — javascript: above all, which would otherwise run as the page displaying the diagram — are refused. The check runs again at render time, so hand-written VGL cannot smuggle one into a published SVG either.

The badge is a real SVG link, so an exported SVG stays clickable wherever it is embedded (inline or via <object>; an SVG inside an <img> is inert by browser design).

Comments

// to end of line, anywhere in the document. Comments are not discarded: a comment belongs to the declaration it stands above, or follows on the same line, and is written back on save or export.

An element's leading comments are the whole block above it, back to the previous declaration — a blank line inside the block does not break it, so a section banner keeps its place:

// ==========================================
// TOP LEVEL - Undesirable Effects
// ==========================================

// Top row
node ude1: UndesirableEffect "Suppliers display a less uniform front";

A comment with nothing to belong to is dropped: before a closing brace, inside a vnotation block, or after the final }.

comment is reserved as an attribute name. [comment: "text"] is an equivalent way to attach one — useful when generating VGL programmatically — and it re-exports as a // text line.

Type inference and minimal syntax

Everything optional, omitted:

vgraph minimal: IBIS "Minimal Example" {
    node q1: Question "Which database should we use?";
    node a1: Answer "PostgreSQL";
    node a2: Answer "MongoDB";
    node p1: Pro "ACID compliance";
    node c1: Con "More complex setup";

    edge q1 -> a1;      // inferred: answered_by
    edge q1 -> a2;
    edge a1 -> p1;      // inferred: supports
    edge a1 -> c1;      // inferred: objects_to
}