Skip to content

C4-PlantUML DSL reference

What parseC4 in @liminis/diagrams/core actually recognizes — derived directly from ELEMENT_MACROS and REL_MACROS in src/core/parser.ts, not from memory or the C4-PlantUML library’s own docs. This is a snapshot as of writing this doc — there is no automated check keeping it in sync with parser.ts; if a macro is added or removed there later, this file can silently go stale. If something here disagrees with the parser, trust the parser.

The parser is a hand-written line parser, not a full PlantUML grammar. It recognizes a fixed set of macro names; anything else on a line that isn’t blank, a comment, or one of the directives below is reported as a parse error (Unknown macro / Unrecognized syntax) — it does not silently ignore arbitrary PlantUML.

Every macro takes a leading unquoted alias (becomes C4Element.id), then arguments in one of two orders:

  • system-style: (alias, "label", "description")
  • detail-style: (alias, "label", "technology", "description")

label becomes C4Element.name; technology/description (when present) become properties.tech / properties.description.

Macro Element type Shape External Arg order Boundary ({ })?
Person person rectangle no system no
Person_Ext person rectangle yes system no
System system rectangle no system no
System_Ext system rectangle yes system no
SystemDb system cylinder no system no
SystemDb_Ext system cylinder yes system no
SystemQueue system queue no system no
SystemQueue_Ext system queue yes system no
Container container rectangle no detail no
Container_Ext container rectangle yes detail no
ContainerDb container cylinder no detail no
ContainerDb_Ext container cylinder yes detail no
ContainerQueue container queue no detail no
ContainerQueue_Ext container queue yes detail no
Component component rectangle no detail no
Component_Ext component rectangle yes detail no
ComponentDb component cylinder no detail no
ComponentDb_Ext component cylinder yes detail no
ComponentQueue component queue no detail no
ComponentQueue_Ext component queue yes detail no
System_Boundary system rectangle no system yes
Container_Boundary container rectangle no system yes
Enterprise_Boundary system rectangle no system yes
Boundary system rectangle no system yes
Deployment_Node system rectangle no detail yes
Deployment_Node_L system rectangle no detail yes
Deployment_Node_R system rectangle no detail yes
Node system rectangle no detail yes
Node_L system rectangle no detail yes
Node_R system rectangle no detail yes
InfrastructureNode component rectangle no detail no
InfrastructureNode_Ext component rectangle yes detail no

A macro whose “Boundary” column is yes is parsed the same as any other element, but a line ending in { opens a nested scope: every element macro up to the matching } gets parent set to this element’s alias, and is also collected into this element’s children array (see the data model for how parent/children relate). External elements (_Ext variants) get properties.external = true, which renderers use to draw the dashed “external system” style.

Verified example — parsing all six deployment/infrastructure macros (this combination has no prior test coverage in the package, so this doc is the first time these argument orders were exercised end-to-end):

parseC4(`
Deployment_Node(dn, "Deployment Node", "AWS")
Node(nd, "Node", "K8s")
InfrastructureNode(inf, "Infra Node", "Nginx")
InfrastructureNode_Ext(infe, "Infra Node Ext", "CDN")
`)

produces (trimmed):

[
{ "type": "system", "id": "dn", "name": "Deployment Node",
"properties": { "style": "boundary", "tech": "AWS" } },
{ "type": "system", "id": "nd", "name": "Node",
"properties": { "style": "boundary", "tech": "K8s" } },
{ "type": "component", "id": "inf", "name": "Infra Node",
"properties": { "tech": "Nginx" } },
{ "type": "component", "id": "infe", "name": "Infra Node Ext",
"properties": { "external": true, "tech": "CDN" } }
]

Note the third argument ("AWS", "K8s", "Nginx") lands in properties.tech, not description — these are all detail-style macros, so the third positional argument is technology, and a fourth argument would be description.

Which macros can be added from the diagram

Section titled “Which macros can be added from the diagram”

C4InteractiveRenderer’s add-element menu (and applyC4Edit’s add-element edit, from 0.2.0) writes Person, System, Container, Component and the Db variants of the last three (SystemDb, ContainerDb, ComponentDb). _Ext, Queue and deployment nodes are not offered: write them in the source. Empty boundaries can be added too, through the menu’s separate Boundaries group and applyC4Edit’s add-boundary edit: System_Boundary, Container_Boundary and Boundary (Enterprise_Boundary is not offered). A boundary is written as an opening line Container_Boundary(alias, "Label") { and a closing }, inserted together. C4 nesting rules are not enforced — an element or boundary can be added in any boundary, which is what the parser accepts. A new element is written in the minimal argument form, System(alias, "Label"), or with a technology and description if given.

Labels written by an edit are single-line and safe to read back: " is written as ', \ as /, and control characters as spaces. Commas, parentheses, braces and non-ASCII are kept as they are; the parser ignores parentheses and braces inside quoted arguments.

Rel and its variants all take (source, target, "label", "technology") — technology is optional. If present, the rendered label becomes "label [technology]".

Macro Meaning
Rel Generic relationship, source → target
Rel_D, Rel_U, Rel_L, Rel_R Same as Rel; the suffix is a PlantUML layout hint (down/up/left/right) that this parser does not use — it affects nothing here
Rel_Back Semantically source → target, drawn as if reversed in PlantUML; this parser stores it identically to Rel
Rel_Neighbor Same as Rel, for elements PlantUML would otherwise place far apart; no effect here
BiRel, BiRel_D, BiRel_U, BiRel_L, BiRel_R Bidirectional; stored identically to Rel — this package does not render a bidirectional arrowhead differently

Verified example:

parseC4(`
Person(a, "A")
Person(b, "B")
Rel(a, b, "Label only")
Rel_D(a, b, "Down label", "tech")
BiRel(a, b, "Bi label", "tech2")
`)

produces:

[
{ "sourceId": "a", "targetId": "b", "label": "Label only" },
{ "sourceId": "a", "targetId": "b", "label": "Down label [tech]" },
{ "sourceId": "a", "targetId": "b", "label": "Bi label [tech2]" }
]

All three collapse to the same C4Relationship shape — the directional/bidirectional distinction in the macro name has no effect on the parsed output.

Directives: what’s recognized-and-applied vs. recognized-and-stripped

Section titled “Directives: what’s recognized-and-applied vs. recognized-and-stripped”

Not everything the parser recognizes is inert. LAYOUT_TOP_DOWN and LAYOUT_LEFT_RIGHT genuinely change the rendered diagram — they set C4Diagram.direction, which layoutC4Diagram passes to dagre as rankdir. Everything else in this table is parsed and thrown away.

Directive Effect
LAYOUT_TOP_DOWN() Applied. Sets diagram.direction = 'down' → dagre rankdir: 'TB' (also the default with no directive)
LAYOUT_LEFT_RIGHT() Applied. Sets diagram.direction = 'right' → dagre rankdir: 'LR'
@startuml, @enduml Recognized, stripped — no effect
!include ... Recognized, stripped — the included file’s content is never fetched or inlined
!define ... Recognized, stripped
SHOW_LEGEND() and other SHOW_* macros Recognized, stripped — this package always draws its own legend logic, independent of this directive
HIDE_* macros Recognized, stripped
title ... Recognized, stripped

Verified example — confirming LAYOUT_LEFT_RIGHT changes rendered positions, not just the parsed AST:

const { diagram } = parseC4(`
LAYOUT_LEFT_RIGHT()
Person(user, "User", "End user")
System(app, "App", "Main app")
Rel(user, app, "Uses")
`);
// diagram.direction === 'right'
const layout = layoutC4Diagram(diagram);
// user: { x: 40, y: 40 }
// app: { x: 260, y: 53 } ← to the right of user, not below it

And confirming the genuinely inert directives really are stripped with zero effect on the parsed element count:

parseC4(`
@startuml
!include https://example.com/C4_Context.puml
SHOW_LEGEND()
title Some Title
Person(user, "User", "End user")
@enduml
`)
// errors: []
// elements.length === 1 (just "user" — every directive line contributed nothing)

Any macro name not in the tables above (element or relationship) produces an Unknown macro parse error — the parser does not silently accept arbitrary C4-PlantUML syntax beyond what’s listed here.