Element types
Every element kind with its fields. Scene schema has the document around them.
Any element can be hidden with visible: false. The engine still lays it out, so it keeps its space, but doesn’t draw it, or any edge with an end at it. A hidden frame hides only its own box and title: its members are drawn. A group draws no box, so hiding one leaves its members drawn too.
Node
The primary diagram element - a shape with a label.
{
"id": "my-node",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "API Gateway"
}
The engine places a node written without a layout, and after the first save keeps its position in the node’s layout, unless:
- a node that grows needs the room (Making room)
- a new node’s edge label needs more room than the column it joins
- a new task in a pool needs room in its lane or a column of its own
- a node an edit inserts in a flowchart needs room along the flow, and the node lies past it
- a node an edit adds to a frame without a
layouthas no room there, and the node lies past that frame - an AWS diagram’s row or column grows for a node or a spanning frame’s header an edit adds, or for the room round a tier frame, and the node lies past it
- an edit moves an AWS Region’s column right to keep a labeled line into it clear, and the node is in the column or right of the Region
- a Google Cloud diagram’s row, zone column, Region or project’s box grows for what an edit adds or a group’s title it widens, or a gap between two Regions, two projects or two zone columns opens for a line it adds, and the node lies past it, or a line it adds past a tier ends in the node, which moves under it
- an edit finds the boxes of a Google Cloud diagram’s sibling projects saved overlapping, and the node is in the project listed later or right of it
- the Google arrangement moves it to stay over a gap, centered on its tiers or clear of a line
- it is joined only to a load balancer that moves to stay over the gap between two Regions, and stands in the load balancer’s row or outside the boundary
- a layer in a stack of layers grows for a card an edit adds to it or moves into it, or an edit adds a layer, and the node lies in a later layer
- an edit moves it into a layer, and it doesn’t already stand on that layer’s row, so the layer places it there
- an edit moves it to another lane
- a frame added or deleted around it would leave frames overlapping or a frame holding a node that isn’t its member
- an
orderconstraint you add finds its two nodes the wrong way around
Positions are kept has the details. Give a layout ({ mode: "absolute", x, y, width, height }) only for an exact position or a feature that needs one, such as autoSize (Position shorthand).
Icons
Nodes can display an optional icon above the label. The icon and the label’s lines are placed as one stack, 4 px apart, and a wrapped label aligned left or right (textStyle.align) takes its icon to the same side. Set the icon field to a semantic key ({family}:{id}) or a URL:
{
"id": "db",
"kind": "node",
"nodeType": "database",
"shape": "roundedRect",
"label": "PostgreSQL",
"icon": "lucide:database"
}
Built-in icons (lucide family): server, database, credit-card, cloud, hard-drive, cpu, monitor, globe, smartphone, shield, lock, unlock, key, wifi, network, code, terminal, git-branch, git-merge, package, boxes, layers, file-code, table, bar-chart, filter, search, mail, message-square, bell, settings, wrench, refresh-cw, clock, calendar, zap, activity, user, users, user-check, check-circle, alert-triangle, x-circle, info, arrow-right, arrow-left, plus, minus, external-link, upload, download, trash
AWS icons (aws family): the official AWS Architecture Icons, about 780 of them: service icons, resource icons (an internet gateway, a load balancer, an ECS task), general icons (users, client, internet) and group icons. AWS icon keys lists every key with AWS’s name for it. Keys follow draw.io’s AWS shape names where draw.io has one, and a short form of AWS’s name otherwise. The ones AWS diagrams use most:
| Use | Keys |
|---|---|
| Edge and DNS | aws:route53, aws:cloudfront, aws:waf, aws:shield, aws:api-gateway |
| Network | aws:vpc, aws:internet-gateway, aws:nat-gateway, aws:application-load-balancer, aws:network-load-balancer, aws:vpc-endpoints, aws:transit-gateway, aws:direct-connect, aws:vpn-gateway |
| Compute | aws:ec2, aws:ec2-instance, aws:lambda, aws:ecs, aws:ecs-service, aws:ecs-task, aws:eks, aws:fargate, aws:auto-scaling |
| Data | aws:rds, aws:aurora, aws:dynamodb, aws:elasticache, aws:s3, aws:s3-bucket, aws:efs, aws:redshift, aws:opensearch-service |
| Integration | aws:sqs, aws:sns, aws:eventbridge, aws:step-functions, aws:kinesis |
| Security and operations | aws:iam, aws:cognito, aws:kms, aws:secrets-manager, aws:cloudwatch, aws:cloudtrail |
| People and places | aws:users, aws:user, aws:client, aws:mobile-client, aws:internet, aws:office-building, aws:server |
Some keys have aliases that name the same icon: aws:alb, aws:nlb, aws:igw, aws:nat, aws:tgw, and others AWS icon keys lists. Every key of Zindex’s earlier AWS pack, such as aws:route53 and aws:elb, still names its icon, as a key or an alias, so saved diagrams keep their icons.
AWS icons are drawn as AWS ships them: never recolored by a theme or adapted in a dark preview, at AWS’s size for the kind of icon whatever the node’s box (a service icon 70 px, a resource or general icon 42 px, a group icon 35 px), with the label below, wrapped in lines of even length at most 160 px wide, whatever the node’s width. An icon AWS ships in a light and a dark variant (Users, the AWS Cloud logo) is drawn in the one that reads on what is under it. An AWS icon draws alone, without its node’s shape, whatever the shape says: a database node’s cylinder isn’t drawn under its icon. To draw the shape behind the icon, set a fill other than white on the node. A nodeFill other than white in the scene’s palette does the same for every AWS icon. An externalSystem node keeps its gray dashed box with the icon inside, and its edges end on the box. A node that draws its icon alone has its edges end on the icon, and an edge into or out of its bottom ends under the label. Auto-layout lines icon-only nodes up on their icons and lets their labels hang below, so icons in a row stay level whatever their labels’ line counts.
AWS Architecture Icons, Release 24 (2026-07-31), © Amazon Web Services, Inc. or its affiliates. Drawn unmodified in architecture diagrams, as AWS allows: https://aws.amazon.com/architecture/icons/. Zindex is not affiliated with or endorsed by AWS.
Google Cloud icons (gcp family): Google’s product icons, about 250 keys. Core products such as Compute Engine, GKE, Cloud Run, Cloud SQL and BigQuery have their own icon, and every other product draws its category’s. Google Cloud icon keys lists every key; for a product it doesn’t list, use its category’s key, such as gcp:category-databases, and name the product in the label. The ones Google Cloud diagrams use most:
| Use | Keys |
|---|---|
| Edge and DNS | gcp:cloud-load-balancing, gcp:cloud-armor, gcp:cloud-cdn, gcp:cloud-dns, gcp:apigee |
| Network | gcp:vpc, gcp:cloud-nat, gcp:cloud-router, gcp:cloud-vpn, gcp:cloud-interconnect |
| Compute | gcp:compute-engine, gcp:gke, gcp:cloud-run, gcp:cloud-run-functions, gcp:app-engine |
| Data | gcp:cloud-sql, gcp:alloydb, gcp:spanner, gcp:firestore, gcp:bigtable, gcp:memorystore, gcp:cloud-storage, gcp:bigquery |
| Integration | gcp:pubsub, gcp:eventarc, gcp:workflows, gcp:cloud-tasks, gcp:cloud-scheduler, gcp:dataflow |
| Security and operations | gcp:identity-and-access-management, gcp:secret-manager, gcp:key-management-service, gcp:cloud-logging, gcp:cloud-monitoring |
| People and places | gcp:users, gcp:user, gcp:mobile, gcp:browser, gcp:laptop, gcp:server, gcp:on-premises, gcp:internet |
Some keys have aliases that name the same icon, such as gcp:lb, gcp:gcs, gcp:iam, gcp:cloud-functions and gcp:kubernetes-engine; Google Cloud icon keys lists them all.
A node with a gcp:* icon draws as Google’s product card, whatever its shape: the icon at the left, then the node’s label in bold over Google’s name for the product. Leave shape out, and give the node a label that says what it does, such as “Orders API”; the card adds “Cloud Run” under it. An externalSystem node keeps its gray dashed box, and BPMN, sequence, ER, org chart and UI flow node types keep their own drawing. Cards keep their colors on every canvas, and Google’s icons are drawn as Google ships them.
Rendering: Google Cloud cards has the card’s sizes, wrapping, colors and stacks, and Rendering: Google Cloud groups the groups they sit in.
Google Cloud product icons (Updated May 2026), from https://cloud.google.com/icons. Google Cloud and Google’s product names and icons are trademarks of Google LLC. Zindex is not affiliated with or endorsed by Google. People, devices and places draw Google’s Material Symbols (Apache License 2.0, https://github.com/google/material-design-icons).
Built-in icons are embedded as base64 data URIs in rendered SVG and PNG, so the image needs no other request; an AWS or Google Cloud icon drawn more than once is written once and reused. Lucide icons automatically match the node’s text color for theme compatibility, adapted with it in dark, blueprint and sketch previews. An icon of your own is drawn wherever the image is when you give it as a data: URI. An icon given as a URL stays a link most viewers don’t load, and a check or save returns the warning ASSET_URI_POLICY_VIOLATION for it (Rendering: Icon rendering).
Only the keys above and those on AWS icon keys and Google Cloud icon keys exist. Any other key gets an ICON_NOT_FOUND warning when you save, edit or validate the scene. The node keeps the icon’s room, empty: a gcp:* node still draws its card, an aws:* node its label, and any other node its box.
The warning’s fix names up to three keys spelled like it, or icons whose name or keywords hold its words (aws:queue names aws:sqs, gcp:redis names gcp:memorystore), or the families there are. Remove an icon with updateNode and icon: null.
Example scene. A small AWS architecture using aws:* icons, each drawn as its icon alone:
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "aws-infra",
"title": "AWS Infrastructure",
"canvas": { "width": 900, "height": 280 }
},
"elements": [
{ "id": "cf", "kind": "node", "nodeType": "service", "label": "CloudFront", "icon": "aws:cloudfront" },
{ "id": "api", "kind": "node", "nodeType": "service", "label": "API Gateway", "icon": "aws:api-gateway" },
{ "id": "lambda", "kind": "node", "nodeType": "service", "label": "Handler", "icon": "aws:lambda" },
{ "id": "db", "kind": "node", "nodeType": "database", "label": "DynamoDB", "icon": "aws:dynamodb" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "cf" }, "to": { "elementId": "api" } },
{ "id": "e2", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "lambda" } },
{ "id": "e3", "kind": "edge", "from": { "elementId": "lambda" }, "to": { "elementId": "db" } }
]
}
Example scene. A small Google Cloud architecture using gcp:* icons, each drawn as Google’s card, its label above the product’s name:
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "gcp-infra",
"title": "Google Cloud Infrastructure",
"canvas": { "width": 900, "height": 280 }
},
"elements": [
{ "id": "lb", "kind": "node", "nodeType": "service", "label": "External load balancer", "icon": "gcp:cloud-load-balancing" },
{ "id": "api", "kind": "node", "nodeType": "service", "label": "Orders API", "icon": "gcp:cloud-run" },
{ "id": "db", "kind": "node", "nodeType": "database", "label": "Orders database", "icon": "gcp:cloud-sql" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "lb" }, "to": { "elementId": "api" } },
{ "id": "e2", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "db" } }
]
}
Shapes
| Shape | Description |
|---|---|
rect | Rectangle |
roundedRect | Rounded rectangle |
ellipse | Ellipse / circle |
diamond | Diamond / rhombus |
cylinder | Database cylinder |
bucket | Object-storage bucket |
pill | Pill / stadium |
hexagon | Hexagon |
parallelogram | Parallelogram (input and output) |
cloud | Cloud shape |
box3d | Isometric 3D box |
textBox | Text container (renders as rect) |
iconBox | Icon container (renders as rect) |
document | Document: a box with a wavy bottom, the label above the wave |
subroutine | Predefined process (a subroutine): a box with a line just inside each side, the label between the lines |
A parallelogram leans by half its height, at most a quarter of its width. A hexagon’s side points stand a quarter of its height out from its top’s corners, at most a quarter of its width. The engine widens either shape so its label fits between the slanted sides, unless textStyle.wrap keeps the width (Node size and wrapped text). Every shape is valid in every family.
Shape is optional. Without one, a node gets its nodeType’s default; give a shape only for a different glyph:
nodeType | Default shape |
|---|---|
er.entity, er.weakEntity | rect |
er.attribute | ellipse |
er.relationship | diamond |
workflow.task, workflow.subprocess | roundedRect |
workflow.start, workflow.end, workflow.timer, workflow.error, workflow.intermediate*, workflow.terminate, workflow.message* | ellipse |
workflow.gateway*, workflow.decision | diamond |
service, actor, queue, externalSystem, process, org.person, org.role, uiflow.screen, uiflow.modal | roundedRect |
database, storage | cylinder |
objectStorage | bucket |
event, uiflow.entry, uiflow.exit | ellipse |
network.cloud | cloud |
iconNode | iconBox |
decision | diamond |
document | document |
| Any other / unknown | rect |
box3d example:
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "rack-topology",
"title": "Datacenter Rack",
"canvas": { "width": 900, "height": 260 }
},
"elements": [
{ "id": "edge-fw", "kind": "node", "nodeType": "service", "shape": "box3d", "label": "Edge Firewall" },
{ "id": "lb", "kind": "node", "nodeType": "service", "shape": "box3d", "label": "Load Balancer" },
{ "id": "app", "kind": "node", "nodeType": "service", "shape": "box3d", "label": "App Servers" },
{ "id": "storage", "kind": "node", "nodeType": "database", "shape": "box3d", "label": "Storage Array" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "edge-fw" }, "to": { "elementId": "lb" } },
{ "id": "e2", "kind": "edge", "from": { "elementId": "lb" }, "to": { "elementId": "app" } },
{ "id": "e3", "kind": "edge", "from": { "elementId": "app" }, "to": { "elementId": "storage" } }
]
}
Node types
nodeType says what a node is. Family types change how a node is drawn and sized (BPMN events and gateways, ER tables, sequence nodes, org cards, UI flow screens), and every type picks the default shape below.
Generic node types: generic, service, database, queue, actor, note, decision, document, process, container, externalSystem, storage, objectStorage, event, iconNode.
Storage convention. database (a cylinder) is for row, key, document and search stores, such as Postgres, Redis, Elasticsearch and DynamoDB. objectStorage (a bucket) is for blob storage, such as S3, GCS, Azure Blob, MinIO and R2, as cloud reference architectures draw it. In a diagram with AWS icons, give the node its aws:* icon instead, which draws alone (Icons), as AWS’s reference architectures draw each service. In one with Google Cloud icons, give it its gcp:* icon, which draws Google’s card.
Decision convention. A decision (a diamond) asks a question, and the label on each of its exits is the answer that exit stands for. In a flowchart, an exit labeled yes runs straight on and one labeled no turns to the right, or below when the flow runs left to right or right to left (Diagram families: Flowcharts). Elsewhere, including other labels and a flowchart with a frame that has no layout, each branch leaves toward wherever its target lands.
Family-specific node types use dot-namespaced values:
Workflow: workflow.start, workflow.end, workflow.messageStart, workflow.messageEnd, workflow.terminate, workflow.task, workflow.subprocess, workflow.decision, workflow.gateway, workflow.gatewayParallel, workflow.gatewayInclusive, workflow.gatewayEvent, workflow.timer, workflow.error, workflow.intermediateTimer, workflow.intermediateMessage, workflow.intermediateError, workflow.intermediateThrowMessage
workflow.decision renders the label INSIDE the diamond, as flowcharts do. The four workflow.gateway* types follow the BPMN convention and render the label EXTERNALLY, below the diamond (above it in some vertical flows: Rendering), because their diamond interiors carry a marker (x, +, circle, pentagon) and there is no room for prose. Pick workflow.decision for a plain decision diamond; pick a workflow.gateway* type when the BPMN gateway semantics matter.
ER: er.entity, er.weakEntity, er.attribute, er.relationship
er.entity and er.weakEntity support compartmented rendering when extensions.columns is provided. Each column is an object with name (required), type (optional), pk (boolean), fk (boolean), unique (boolean), nullable (boolean) and comment (kept, not drawn). The shape { name, type, key: "PK" | "FK", unique?, nullable? } is also accepted as an alias - the engine reads either form. A column that is both a primary and a foreign key needs pk and fk, since key holds one. The renderer produces a table-like box with a colored header bar (via accentColor), separator, and attribute rows with PK/FK badges (both on a column that is both) and right-aligned types. Without extensions.columns, entities render as plain rectangles.
The unique and nullable flags don’t change the visible compartment but feed the auto-inference passes for column-row anchoring (see Column-row anchored edges) and Crow’s Foot cardinality glyphs (see Crow’s Foot cardinality).
Mutating columns on an existing entity. Use updateNode with the FULL replacement extensions.columns array - the array is replaced wholesale, not merged. There is no addColumn / removeColumn / updateColumn op; the valid operations are listed in Operations. To add a column, fetch the current entity (e.g. diagram_get with view: "dsp"), append to its extensions.columns, and call updateNode with the complete array. To remove a column, filter it out and call updateNode with what remains.
Auto-sizing. When extensions.columns is set, the layout engine sizes the entity rect to fit the longest column row plus header and (rows × rowHeight) - author-declared layout.width / layout.height are treated as a minimum. If you set width: 100 on an entity whose longest column row measures 200px, the rect grows to 200px to prevent overflow; if you set width: 400 to leave breathing room, the rect stays at 400px. A save stores the size the rect is drawn at, so the 100 above is saved as 200. Entities the engine places (no explicit layout) are sized from intrinsic measurements directly, and measured again when an edit changes their columns.
{
"id": "users",
"kind": "node",
"nodeType": "er.entity",
"shape": "rect",
"label": "Users",
"extensions": {
"columns": [
{ "name": "id", "type": "int", "pk": true },
{ "name": "email", "type": "varchar(255)" },
{ "name": "role_id", "type": "int", "fk": true }
]
}
}
Column-row anchored edges (auto-inference)
When an edge’s label exactly matches the name of a column declared in either endpoint’s extensions.columns, the platform automatically promotes the edge to a column-row anchor: the FK edge terminates at the named column row inside the entity, as database diagram tools draw it, and the label isn’t drawn, because the column position now carries the FK identity. The edge keeps the label as written. Agents can also set endpoint.column directly:
{
"id": "fk_orders_users",
"kind": "edge",
"from": { "elementId": "orders", "column": "user_id" },
"to": { "elementId": "users", "column": "id" }
}
When the label matches a column on BOTH endpoints (the rare id-as-label case), both ends get the column anchor - the line goes column-to-column. When the label matches only one side, only that endpoint is column-anchored; the other terminates at the entity’s outer face.
The API doesn’t report which labels the engine promoted, so check the drawing when a label matters.
To draw the label as well, set style.forceLabel: true on the edge, with the label or in a later edit. The edge still anchors at the column the label names, and its cardinality at that end is inferred from that column.
{
"id": "fk_orders_users",
"kind": "edge",
"from": { "elementId": "orders" },
"to": { "elementId": "users" },
"label": "user_id",
"style": { "forceLabel": true }
}
When endpoint.column is set but the named column is not declared in the endpoint entity’s extensions.columns, the platform emits an EDGE_COLUMN_NOT_FOUND warning diagnostic and falls back to face-center anchoring on that endpoint.
PK fallback for the unset side. When endpoint.column is undefined and the endpoint entity has a single PK column (pk: true or key: "PK"), the endpoint anchors at the PK row automatically. This means a typical FK edge can omit the column on the PK-side endpoint and still draw cleanly into the PK row inside the target entity:
{
"id": "fk_orders_users",
"kind": "edge",
"from": { "elementId": "orders", "column": "user_id" },
"to": { "elementId": "users" }
}
Self-FK edges (a parent_id-style column referencing the same entity’s PK) work the same way - the source side anchors at the FK row, the target side falls back to the PK row, and the renderer draws a U-bracket on the right face spanning the two rows.
Entities with no PK or composite PKs (multiple pk: true columns) skip the PK fallback and anchor at the entity face instead.
Crow’s Foot cardinality (auto-inference)
ER edges render Crow’s Foot glyphs at each endpoint based on the endpoint’s cardinality field. Valid values: one, many, zero-or-one, zero-or-many, one-or-many.
When cardinality is omitted on an endpoint and the endpoint resolves to a known column (via endpoint.column, a label naming the column, with or without forceLabel, or the PK fallback above), the engine infers the value from the column metadata:
| Column metadata | Inferred cardinality |
|---|---|
The only PK column (pk: true or key: "PK") | one |
| One of several PK columns | many |
FK column, unique + nullable: true | zero-or-one |
| FK column, unique | one |
FK column, nullable: true | zero-or-many |
| FK column (no other flags) | many |
An FK column is unique when it has unique: true or is its entity’s only PK column. A column with both pk and fk set is inferred as an FK column and shows both badges. So a table that shares its parent’s key (user_profiles.user_id, the whole primary key) is one-to-one with that parent, and a join table keyed by its foreign keys (post_tags with post_id and tag_id) is many-to-one with each parent, when each edge names its column (endpoint.column, or a label matching the column name). Without one, a composite key has no single row to fall back to, so that end stays empty and FAMILY_ER_MISSING_CARDINALITY reports it.
Author-set cardinality is always preserved; auto-inference only fills in undefined endpoints. Inferred values aren’t saved with the edge: every save infers them again from the columns as they are then, so a glyph follows its column (marking an FK column unique: true turns its crow’s foot into a bar), and view: "dsp" shows the edge as written. To fix an end’s value, set cardinality with updateEdge; to have it inferred again, send that end without cardinality. Self-loops still get inferred values, but the renderer skips Crow’s Foot glyphs on self-loops because the U-bracket geometry is too tight to fit two readable markers.
Sequence: sequence.lifeline, sequence.actor, sequence.boundary, sequence.control, sequence.entity, sequence.database, sequence.collections, sequence.queue, sequence.activation, sequence.note
The first eight are participants: each heads a column of the diagram. sequence.lifeline is a box and sequence.actor a stick figure. The other six say what a participant is, as UML’s stereotypes do:
| Node type | The participant is |
|---|---|
sequence.boundary | An interface to the outside |
sequence.control | Logic that coordinates |
sequence.entity | A domain object |
sequence.database | A database |
sequence.collections | Many of one thing |
sequence.queue | A queue |
The type changes only how the head and foot are drawn (Rendering: Lifeline rendering). Messages, notes, bars, boxes and order work on every participant as they do on a lifeline. Where these pages say lifeline for a column, any of the eight will do.
Lifeline headers auto-size to fit their labels (the 100 px width is a floor, not a cap), so multi-word participant names like "Compute Endpoint\n(Metadata)" fit in the header. Each lifeline also renders a matching foot bar at the bottom of the diagram by default, as UML does - do not author duplicate node shapes for the bottom row, and set showLifelineFeet: false in the document’s top-level extensions (not scene.extensions, which isn’t kept) if you want to suppress the foot bars.
sequence.activation is a bar on a lifeline while it is busy. Set extensions.startsAt to the message that starts it and extensions.endsAt to the one that ends it, and leave layout out: the bar is drawn on the lifeline startsAt arrives at, from that arrow to endsAt’s, or one row tall without endsAt, and moves with its messages. Bars that overlap on one lifeline are stacked, and create and destroy messages start and end lifelines (Rendering: Lifeline rendering).
sequence.note is the UML annotation primitive for prose between messages - for example a “Postgres crashes” callout. Set extensions.anchor to a participant’s id and the note centers OVER that participant, as UML notes do; pass a string array of two or more participant ids and the note spans across them (also centered-over semantics, leftmost to rightmost). Notes interleave vertically with messages by their position in the elements array: in a scene, place the note element BETWEEN the two messages it should appear between; in an edit, create it with after naming the message it follows, or the fragment to go below it (Operations: Order in a sequence diagram). Renders as a rect with a folded top-right corner: a soft yellow fill (dark olive under dark and sketch, navy under blueprint) and a gold border, unless its style or the palette sets fill or stroke; colors it sets are adapted in dark, blueprint and sketch previews like any other. Its folded corner is its fill a step darker in every render, at least as far as a light note’s fold (about 1.41:1), so it shows on a dark note too; a very dark note can fold only as far as black, and a translucent note’s fold keeps its alpha.
To put a note beside a lifeline instead of over it, give it one participant’s ID as its anchor and extensions.side, "left" or "right": "extensions": { "anchor": "auth", "side": "right" }. An array anchor, even of one ID, is drawn over its lifelines, and side there gets FAMILY_SEQ_NOTE_SIDE_IGNORED (Rendering: Lifeline rendering).
A note with no anchor is drawn over the lifelines of the message above it, and FAMILY_SEQ_NOTE_INVALID_ANCHOR warns: set an anchor to place it yourself. A self-message has one lifeline, so the note goes over it.
- Beside one. With
sideand noanchor,"left"puts the note left of that message’s leftmost lifeline and"right"right of its rightmost. - No message above it. A note above every message goes over the first message below it. In a diagram with no message it goes across every lifeline, or beside the leftmost (
"left") or rightmost ("right") lifeline withside.
A diagram with no lifeline draws no note. A note whose anchor names no lifeline that exists isn’t drawn (FAMILY_SEQ_NOTE_ANCHOR_NOT_FOUND): name one that does. The saved scene keeps the note without an anchor, so it follows whichever message is above it.
Network: network.server, network.router, network.switch, network.firewall, network.cloud, network.client
Org Chart: org.person, org.role, org.department
org.person and org.role render as structured person cards with bold name, muted title (parsed from label split on \n), left accent stripe (via accentColor style), and optional left-aligned icon (36px). org.department falls through to generic shape rendering.
UI flow: uiflow.screen, uiflow.modal, uiflow.entry, uiflow.exit
Text style
Nodes in a scene accept an optional textStyle object that controls how the label text is rendered. createNode takes it (fields left out take their defaults); updateNode and setText change only the fields they give. An edge’s label takes wrap alone (Label wrapping).
| Property | Values | Default | Description |
|---|---|---|---|
wrap | "auto", "none", "word", "character" | "auto" | Text wrapping mode |
align | "left", "center", "right" | "center" | Horizontal text alignment |
verticalAlign | "top", "middle", "bottom" | "middle" | Vertical text alignment |
{
"id": "description-box",
"kind": "node",
"nodeType": "note",
"shape": "roundedRect",
"label": "This is a longer description that wraps across multiple lines within the node boundary.",
"textStyle": { "wrap": "word", "align": "left", "verticalAlign": "top" },
"layout": {
"mode": "absolute",
"x": 50, "y": 50,
"width": 220, "height": 120
}
}
How each wrap value sizes and breaks a label (where lines break):
"auto", the default: one line while the node can grow to hold it, up to 250 px of text width (400 px for a diamond; a shape with wider margins, such as a bucket, a little wider). A longer label wraps there in lines of even length, and the node grows taller. The node is at least as wide as the label’s widest piece that can’t break, such as a long word; a label with nowhere to break stays on one line. A widerlayoutkeeps one line up to its own width."none": one line however long, the node widening to fit. Diagrams saved before"auto"store"none": set"auto"withupdateNodeorsetTextto wrap them."word": wraps to the node’s width; a word wider than the node runs past its edges."character": as"word", and breaks such a word between its characters. Use it for long identifiers and URLs.
In every mode, \n starts a new line. In a diamond, wrapped lines sit in the largest rectangle inside it, half its width and height.
align and verticalAlign place the label whether or not it wraps: at the center, or half the font size in from a side, the top or the bottom, with the node’s icon above the label on its side. Nodes that draw their own text ignore both: org chart person and role cards, UI flow screens and modals, ER tables with columns and sequence nodes; so does the label a BPMN event or gateway has outside its shape.
A character the images can’t draw, such as a letter of Arabic, Hebrew or Thai, is drawn as an empty box, and saving, editing or validating the scene returns a CHARACTER_NOT_DRAWN warning (Rendering: Text and scripts).
Where lines break
Wrapped text breaks by the Unicode line breaking rules (UAX #14), with Korean kept whole between spaces:
- At a space or a tab, after a hyphen or a slash, and between Chinese or Japanese characters.
- Never inside a word, a number, a date such as
2024-10-07, acamelCaseorsnake_casename, or a dotted name such asa.b. Only"character"breaks one, and only when it is wider than the line. - Never before closing punctuation such as
、,。or」, or a small kana such asッ, and never after opening punctuation such as「.
To let a long word break at a point of your choosing, put a soft hyphen (\u00ad) there: a line that breaks at it ends with a hyphen.
Position shorthand
As a convenience, nodes and frames accept x, y, width, and height as top-level properties instead of nesting them inside a layout object. Text and image elements need the layout object:
{
"id": "quick-node",
"kind": "node",
"nodeType": "service",
"label": "Shorthand",
"x": 50, "y": 100,
"width": 180, "height": 70
}
This is equivalent to specifying layout: { mode: "absolute", x: 50, y: 100, width: 180, height: 70 }. The engine converts the shorthand into the full layout object.
Node size and wrapped text
A placed node’s layout size is a minimum (a node at any position other than x 0, y 0; see Nodes the engine places for the others). textStyle.wrap decides how the label grows it:
"auto", the default: the node widens to fit the label on one line, up to 250 px. Past that the label wraps and the node grows taller. It grows wider only for text with no break point, such as a long word, that is wider than 250 px."none": the node widens to fit the line, however long."word"or"character": the label wraps at the node’swidth, and the node keeps that width.
layout.autoSize is "none" unless you set "content", and "none" doesn’t make a size exact. The width and height you write are a floor: a card whose label needs more grows to fit it, and a wrapped label that overflows its height gets a TEXT_OVERFLOW warning that gives the height it needs. Some layout tools read a fixed size as exact; Zindex doesn’t. For a box of one size, keep its label short enough to fit.
A save stores the size the node is drawn at: a card written 340 wide whose label needs 368.5 is saved at 368.5, and a read shows that width. A growth of 1 px or less isn’t stored. A read, a render and a validate store nothing.
A size smaller than the content needs is repaired on every draw, because the node is drawn at the size its content needs. The next create or edit stores that size, and until then a read of the diagram shows the size you wrote.
A save stores no size for growth alone on:
- A node whose edges dock on a smaller box than it draws. These are a BPMN event or gateway (
workflow.*), auiflow.entryoruiflow.exit, a node that draws its icon alone (anaws:*icon, see Icons), and a card agcp.zonespans (the zone draws a strip under it). Their size is stored where the engine places or moves them, where an edit measures them again, or where their growth pushes a neighbor or a frame border. - A Google Cloud card drawn as a stack (
style.multiple). It keeps the size it was saved at, and the copy’s room is added on every draw. - The height of a node with
autoSize: "content". It stays the one you gave, the minimum (below). - A sequence node, or a node placed relative to another.
Each \n in the label adds a line. Add layout.autoSize: "content" and the engine also gives the node the height its wrapped label and its icon need, padding included, growing it down from its top edge. The height you give is the minimum:
{
"id": "card",
"kind": "node",
"nodeType": "service",
"label": "This label wraps at the width the node is given.",
"textStyle": { "wrap": "word" },
"layout": { "mode": "absolute", "x": 50, "y": 50, "width": 200, "height": 40, "autoSize": "content" }
}
The engine works the height out on every layout, so the node follows its label when an edit changes it. The stored height stays the one you gave. At x 0, y 0 the engine places the node next to its neighbors at that width and height.
A pinned node that grows pushes the nodes below it down, keeping the full spacing from it: the node spacing in a left-to-right flow, the rank spacing in a top-to-bottom one. A frame with its own layout grows to keep it inside, and so does a pool or lane (Layout Engine: Making room). A node that shrinks pulls nothing back. What "content" doesn’t do:
- Size text a node lays out itself. It sizes a label drawn as wrapped text in the node’s box. Org chart people and roles, UI flow screens and modals, ER tables with
columns, and sequence participants, activations and notes lay out their own text, and BPMN events and gateways and UI flow entry and exit points draw their label outside the shape (below it, or above it in some vertical flows: Rendering), so it doesn’t change them. - Labels set to
"auto"or"none". The engine already sizes those nodes to their label.
Without autoSize, a wrapped node keeps the height you give it. If the text, or the text and its icon, doesn’t fit, saving, editing or validating the scene returns a TEXT_OVERFLOW warning for the node, and its fix gives the height they need, the height "content" would give it.
Nodes the engine places
A node at x 0, y 0, or without a layout, isn’t placed yet, and its size is the engine’s to choose. When the engine places it, it gives the node the size its label and icon need, whatever width and height the node had, and stores that size with the position. A label with textStyle.wrap "word" or "character" is measured on one line then, so it no longer wraps, unless the layout also has autoSize: "content": such a node keeps its width, and its height stays the minimum. To give a node a size of its own, give it a position as well. resizeElement refuses a node that isn’t placed yet; resize it in a later edit.
When an edit changes what a placed node shows, the engine measures the node again on each axis where its size was what its old content needed. The content is its label, shape, node type, icon, ER columns or text style, or the font size or weight its style gives it, and the edit doesn’t set the node’s layout. A card the engine sized follows its label both ways, and keeps its place. A size you made bigger than the content needed stays when the label gets shorter, and a longer label still grows the node.
A BPMN event or gateway and a UI flow entry or exit point follow their content on both axes. A node whose label is set to "word" or "character" isn’t measured again. To have the engine choose a node’s size again, send autoLayout with elements naming it. It places the node again, so it can move, and a label set to wrap is measured on one line unless autoSize is "content".
Card-style example. Wrapped text in a node with a width and autoSize: "content" is the pattern for card-style nodes. The width comes from layout, so a card needs one: with coordinates to pin it, or at x 0, y 0 to have the engine place it:
{
"schemaVersion": "0.1",
"scene": {
"id": "text-cards",
"title": "Service Cards",
"canvas": { "width": 720, "height": 180 }
},
"elements": [
{
"id": "gateway",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "API Gateway handles all incoming HTTP requests, performs rate limiting, and routes to downstream services.",
"layout": { "mode": "absolute", "x": 40, "y": 40, "width": 240, "height": 40, "autoSize": "content" },
"textStyle": { "wrap": "word", "align": "left", "verticalAlign": "top" }
},
{
"id": "auth",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Auth Service validates JWT tokens, manages sessions, and enforces RBAC policies across all endpoints.",
"layout": { "mode": "absolute", "x": 440, "y": 40, "width": 240, "height": 40, "autoSize": "content" },
"textStyle": { "wrap": "word", "align": "left", "verticalAlign": "top" }
},
{ "id": "e1", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "auth" } }
]
}
Edge
A connection between two elements, usually nodes. A frame or group can be an end: an edge to a frame ends at its border, for a connection to the whole group rather than one member.
{
"id": "e1",
"kind": "edge",
"from": { "elementId": "node-a" },
"to": { "elementId": "node-b" },
"router": "orthogonal",
"label": "requests"
}
The router picks the side each end leaves and enters (Where an edge enters its target). To choose it yourself, give an endpoint an anchor:
"from": { "elementId": "orders", "anchor": { "side": "left", "offset": 0.25 } }
side is top, right, bottom or left. With side alone the end meets that side and the engine picks the place on it:
- Where the two sides face each other and their faces overlap, it lines the ends up, so the line between them is straight.
- It spreads ends that share the side.
- It slides a straight line past the title of a frame it enters.
A side that faces away from the other node routes round the node. Faces that don’t overlap take a bend.
A BPMN sequence flow or UI-flow transition into a node enters at the target’s center, so a side alone fixes only the face. It takes the straight line only where the ends are less than 16 px off center.
offset (0 to 1) puts the end at that place, from the top of a left or right side or the left of a top or bottom side. The corner distance is the same as for any end (8 px, more past a rounded corner), and a place is below a UI card’s title bar and off a cylinder’s lid seams. The engine doesn’t move a placed end to line it up with another, so two ends given places that don’t line up take a step between them. Two ends placed at one spot are the exception: they are kept 12 px apart where the side has room.
An offset is a fraction of the side as drawn, and a save stores that side’s length in the node’s layout. A card whose label needs more room than the layout.width you wrote is drawn wider on its first draw, so an offset worked out from your width lands off its mark. The save warns with EDGE_OFFSET_ON_GROWN_NODE. Read the saved size and work the offset from it, or use sides. On a node that docks on a smaller box than it draws (list), an offset is a fraction of that box: the shape, the icon, or the card without the strip a zone adds.
An anchored edge never shares a trunk with other edges. updateEdge replaces from and to whole, so send an end’s anchor again with it to keep it. The engine doesn’t move nodes for an anchor. A sequence message, a self-loop and an end with a column ignore their anchor, with the warning EDGE_ANCHOR_IGNORED.
Routers
| Router | Description |
|---|---|
straight | One line between centers, ending on each outline |
orthogonal | Right-angle connectors |
curved | One bowed arc, ending on each outline |
polyline | Right-angle connectors, as orthogonal |
orthogonal is the default. straight and curved edges aren’t routed round other nodes: a lone curve bows to the side that clears them where one does, and an edge through a node gets the warning EDGE_CROSSES_NODE. How each is drawn: Edge routing.
Edge types
Edges can declare an optional edgeType for family-specific connection semantics: "default", "workflow.sequenceFlow", "workflow.messageFlow", "er.relationship", "er.identifying", "sequence.message", "sequence.reply", "sequence.create", "sequence.async", "sequence.destroy", "network.dataFlow", "network.controlFlow", "org.directReport", "org.dottedLine", "uiflow.navigate", "uiflow.back", "uiflow.action". uiflow.back also draws dashed. org.dottedLine renders as a dashed line for matrix/secondary reporting. A type that draws dashed uses 6,3 unless the edge’s style.dash sets a pattern, and [] draws it solid. er.relationship and er.identifying both draw a solid line, as Mermaid and Information Engineering draw an identifying relationship; for a non-identifying relationship, add style.dash (for example [6, 4]) and the line draws dashed.
In a sequence diagram an edge between two participants with no sequence.* type is drawn as a message (Rendering: Message rendering).
Each type comes with its arrowheads, the same whether a scene or a createEdge operation made the edge:
workflow.messageFlow: an open circle at the source and an open triangle at the target (BPMN’s message flow).sequence.asyncandsequence.reply: an open triangle at the target.- Every other type,
defaultincluded: a filled triangle at the target.
An AWS or Google Cloud diagram draws the open arrow, openTriangle, at the target instead. Such a diagram has an AWS or Google Cloud group (an aws.* or gcp.* containerType), or a node with an aws:* or gcp:* icon, groups or not. It does so on an edge whose edgeType is unset, default, or an er.*, network.* or org.* type. workflow.sequenceFlow, sequence.message, sequence.create, sequence.destroy and the uiflow.* types keep the filled triangle, so set endArrow on one of those to draw the open V.
Set endpoints to change them, for example { "endArrow": "none" } for an undirected line. The type’s arrowheads aren’t stored: an edge keeps only those you set that differ from what its type and diagram give, so changing its edgeType changes the rest, and view: "dsp" shows only what you set (an older version can still list its type’s arrowheads; they draw the same). An ER end with a cardinality draws a crow’s-foot mark instead of an arrowhead.
Unless an endpoint’s anchor says otherwise, the type also sets where an edge enters its target: workflow.sequenceFlow and the uiflow.* transitions enter a node’s side at its center, workflow.messageFlow runs straight through two boxes’ overlap, and every other type enters straight across where the nodes line up (Where an edge enters its target).
Label typography
In flowchart, workflow, UI flow and sequence diagrams, an edge label written as EVENT [guard] / action draws its guard and action smaller and muted, the action in italic. Other diagrams, one with no family included, draw edge labels as plain text (Rendering: edge label typography).
Label wrapping
An edge label wider than 200 px, its text and 4 px of padding on each side, wraps into lines in a box at most that wide. A line takes every word that fits, and lines break where a node’s label breaks (where lines break). The edge’s textStyle.wrap sets the rule:
wrap | A label wider than 200 px |
|---|---|
"auto" | Wraps. The default when textStyle is absent |
"word" | Wraps, the same as "auto" |
"character" | As "word", and breaks a word wider than the line between its characters |
"none" | Keeps each line as written, however wide |
\n starts a new line in every mode. Except in "none", each line you write wraps by itself. A label that fits is drawn as written, unless the layout finds it no clean place (below). A word wider than the line stays whole in "auto" and "word".
An edge takes wrap alone, since a label is centered on its line:
- A scene,
createEdgeandupdateEdgerefusealignandverticalAlign, andsetTextignores them. createEdge,updateEdgeandsetTextsetwrap, and an edit that doesn’t mentiontextStylekeeps it.- The engine never adds
textStyleto an edge, and awrapyou send is kept as sent. Send"auto"to undo"none". - The 200 px can’t be changed.
A node’s label has its own rule (Text style). A transition label breaks between its parts first (Rendering: Label width). A saved diagram’s label wider than 200 px, or with no clean place, wraps the next time the diagram is drawn; the images of versions already saved don’t change.
A label with no clean place beside its line can also wrap narrower than 200 px, in two lines, then three (or the lines you wrote, if more). A label that has a clean place keeps its lines. Layout engine: label placement has the rule.
"none" keeps a label as written wherever it goes. A label that can’t break, such as one long identifier, and a sequence message’s label keep their box.
Most edges need no textStyle. This one keeps a long label on one line:
{
"id": "e1",
"kind": "edge",
"from": { "elementId": "orders" },
"to": { "elementId": "ledger" },
"label": "Post a reversal for the item's price, its tax and any shipping charged for it",
"textStyle": { "wrap": "none" }
}
Endpoints
{
"endpoints": {
"startArrow": "circle",
"endArrow": "none"
}
}
startArrow and endArrow are none, triangle, openTriangle, diamond, circle, openCircle, bar or cross. Leave out an arrowhead the edge’s type gives (Edge types). openTriangle is an open V, two strokes with no fill, the arrowhead of AWS’s and Google Cloud’s architecture diagrams; a Google Cloud diagram draws it as Google’s small chevron (Rendering: Google Cloud edges). It is the default in AWS and Google Cloud diagrams (Edge types): set endArrow there only to draw another, "triangle" for a filled one.
cross is an X on the line just short of the node, the size of the filled arrowhead, with the line running through it, as Mermaid’s --x and draw.io’s cross end draw it. It isn’t the X a sequence.destroy message draws at the lifeline it ends.
An end (from or to) can carry an optional cardinality for ER-style crow’s-foot notation:
| Value | Marker | Description |
|---|---|---|
one | | | Exactly one |
many | < | Many (crow’s foot, prongs on the entity) |
zero-or-one | ○| | Zero or one |
zero-or-many | ○< | Zero or more |
one-or-many | |< | One or more |
Numbered steps
step, a whole number from 1 to 99, draws a numbered badge at the start of the edge’s line, as AWS’s architecture diagrams number the path a request takes. stepText is the edge’s line in a step list drawn right of the diagram, and needs step; it is held to the label’s length limit.
{ "id": "e_put", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "uploads" }, "label": "put", "step": 2, "stepText": "The API stores the original in S3." }
Numbers may repeat, and several edges may share one. Steps are drawn in every family. A sequence diagram can also number every message, with autonumber in the document’s top-level extensions; a message’s own step then restarts the count. Layout Engine: Numbered steps has where badges and the list go, how a sequence diagram numbers its messages, and what steps don’t do.
Group
A logical grouping of elements. A group draws nothing (no box, border or title), like a plain Graphviz subgraph or a PlantUML or draw.io group. Its title is written into the SVG as the group’s <title> and isn’t drawn. For a visible box with a title round elements, use a frame.
{
"id": "group-1",
"kind": "group",
"children": ["node-a", "node-b"]
}
Frame
A visual container with a title bar and background. A frame written without layout is sized around its members and is at least as wide as its title. A frame with its own layout keeps that box, unless making room grows or moves it (Making room) or autoLayout without elements drops it, as it does for every frame but a pool, lane or fragment outside org charts and networks. A pool’s or lane’s layout is only a minimum: pools and lanes always grow to hold their members (Container types). A title wider than it runs past its right border, and TEXT_OVERFLOW gives the width it needs (not for pools and lanes, whose titles run along their header strips).
{
"id": "frame-1",
"kind": "frame",
"title": "Backend Services",
"children": ["api", "db"],
"layout": {
"mode": "absolute",
"x": 20, "y": 20,
"width": 500, "height": 300
}
}
Container types
Frames can declare an optional containerType for semantic containment: "generic", "pool", "lane", "subprocess", "partition", "package", "boundary", "fragment" (a sequence combined fragment), "layer", or one of AWS’s or Google Cloud’s groups (below). "pool" and "lane" are BPMN’s swimlanes, which the engine lays out itself (below). "layer" is one row of a stack in an architecture diagram, or one without a family. The layers a frame lists stack in the order listed. A layer the engine doesn’t arrange is placed as a generic frame (Layout engine: Layers).
AWS groups. "aws.cloud", "aws.region", "aws.vpc", "aws.az", "aws.subnet.public", "aws.subnet.private", "aws.securityGroup", "aws.autoScalingGroup", "aws.account" and "aws.corporateDataCenter" draw a frame as AWS draws that group: its color and line, no fill, its group icon in the corner and its title beside it at 14 px (Rendering: AWS groups). Nest them as AWS does: aws.cloud > aws.region > aws.vpc > aws.az > aws.subnet.public and aws.subnet.private. A frame’s style overrides its preset.
In an architecture diagram, or one without a family, the AWS Cloud, Region, VPC, Availability Zone and subnet presets also place what they hold, as AWS’s reference diagrams do: Availability Zones as columns, subnets as rows across them, a gateway on the side of the VPC it faces (on the top when it serves several AZs or the load balancer between two), regional services in a column beside the VPCs, global services in a row above the Regions, users outside AWS Cloud. Leave layout off the frames and their nodes; a preset’s layout is only a minimum. The other four presets only draw, and are laid out as any frame (an account holding Regions is arranged as AWS Cloud is). Nest the placing presets directly: a generic frame round all of a VPC’s Availability Zones, round whole VPCs of a Region, or round subnets next to each other in one zone’s rows (a tier), is read through. Any other frame between a Region and its VPC, or a VPC and its Availability Zones, such as one round some of the zones or an account, is laid out as any frame with the presets inside it, and one between a zone and its subnets puts everything in it on one row; a generic one gets AWS_FRAME_HIDES_GROUPS. Draw a group across zones, such as an Auto Scaling group, as a spanning frame. Layout Engine: AWS architecture diagrams has the whole behavior and what it doesn’t do.
Google Cloud groups. "gcp.cloud", "gcp.project", "gcp.region", "gcp.vpc", "gcp.zone", "gcp.subnet", "gcp.tier", "gcp.instanceGroup" and "gcp.onPremises" draw a frame as Google’s Architecture Center diagrams draw that group: its fill, line and title, rounded corners and no icon (Rendering: Google Cloud groups). Nest them as Google does: gcp.cloud > gcp.project > gcp.region > gcp.subnet > gcp.tier and gcp.instanceGroup. The project is optional, a tier or an instance group can sit in a Region, and gcp.onPremises goes outside gcp.cloud. A frame’s style overrides its preset, except a zone’s strips, which keep Google’s colors.
gcp.cloudwith no title, or titled “Google Cloud”, draws Google’s wordmark in place of its title, and any other title as text (Rendering: Google Cloud groups). To name a project or an environment, use agcp.projectinside the boundary.gcp.vpcandgcp.zoneare spanning frames: write them withspans, notchildren. A VPC spans its subnets, across Regions. A zone spans the nodes in one zone of one Region and draws a strip under each of them.- Google defines no group for a GKE cluster, a node pool or a folder, so none has a preset: draw one as a generic frame. In Google’s arrangement such a frame is laid out as one block in its row, so the cards in it stand in no zone column.
- Google defines no custom groups either. A frame with a
gcp:*icon and no preset is a generic frame, its icon drawn before its title.
In an architecture diagram, or one without a family, the boundary, Region and subnet presets also arrange what they hold, zones as columns and tiers as rows. Leave layout off the frames and their nodes; a group’s layout is only a minimum. Only a tier’s cards stand in zone columns, and a generic frame between the groups, other than one round whole Regions, loses the arrangement. Layout Engine: Google Cloud architecture diagrams has the arrangement and what it doesn’t do.
Frame icon. A frame can have an icon, a family:id key or an image as a data: URI, drawn in its header. An AWS key draws as AWS draws a group icon: 35 px, flush in the top-left corner, the title beside it. A frame with an aws:* icon and no preset is AWS’s custom group, and its border takes the icon’s category color unless stroke or accentColor sets it (Rendering: AWS groups). Any other icon, a Google Cloud key among them, draws 16 px before the title.
It replaces a preset’s icon, and updateFrame changes it or removes it with null. A key no icon has draws nothing and gets ICON_NOT_FOUND.
Frame border. A frame drawn the generic way is dashed 4,4 unless its style.dash says otherwise: [] draws it solid, and any other array is the pattern. Presets take their own, and pools, lanes and fragments keep their own drawing. Each side is dashed on its own, the pattern stretched a little so the side starts and ends on a dash: every corner is drawn, and a side an edge crosses keeps the same rhythm.
Frame color. A frame’s style.accentColor colors its border as stroke would. It colors the title in a shade of the accent that reaches 4.5:1 where the title sits. stroke and textColor each override their part.
- It adds no wash: set
fillto tint the frame. - The title of a pool, a fragment, an AWS or Google Cloud group and an AWS custom group (a frame with an
aws:*icon and no preset) keeps its own color; the border takes the accent. - A Google Cloud zone’s strips ignore it, and a check, save or edit returns
ACCENT_COLOR_NOT_DRAWN: remove it. palette.accentPrimarycolors nodes, not frames.
Where a line crosses. The border of a frame other than a pool, a lane or a fragment breaks with a gap 8 px wide, centered on the crossing. Two crossings less than 16 px apart share one gap, so no stub of border is left between them.
A pool frame’s children are its lanes, frames with containerType: "lane", in the order they stack; each lane’s children are its tasks, events and gateways, or lanes of its own (BPMN’s nested lanes). Leave layout off the pool, the lanes and their nodes. The engine stacks the lanes across the flow, places every node a lane lists inside that lane, fits each lane to its contents (at least 60 px deep, or its title’s length plus 16 px when that is more) and shares columns across lanes and pools. A pool’s or lane’s layout is a minimum: the pool grows right and down from its corner to hold its lanes and members, and a lane’s x and y are ignored, because the pool places its lanes. Layout Engine: Pools and lanes has the whole behavior and what it doesn’t do; Rendering shows how they are drawn.
[
{ "id": "pool", "kind": "frame", "title": "Order to cash", "containerType": "pool", "laneDirection": "vertical", "children": ["sales", "warehouse"] },
{ "id": "sales", "kind": "frame", "title": "Sales", "containerType": "lane", "children": ["start", "check"] },
{ "id": "warehouse", "kind": "frame", "title": "Warehouse", "containerType": "lane", "children": ["pick", "end"] }
]
A fragment frame in a sequence diagram holds messages and notes, and nested fragments, in children, and takes extensions.operator ("alt", "opt", "loop", "par" and so on, drawn as written) and extensions.operands: for each operand after the first, { "startsAt": "<message or note id>", "guard": "else" }. Its title is the first operand’s guard, drawn as written (write its brackets); the renderer adds the brackets round each operand’s guard (write it without them). The engine lays it out with its rows and ignores its layout (Rendering: Combined fragments).
{
"id": "frag_charge",
"kind": "frame",
"containerType": "fragment",
"title": "[charge succeeded]",
"children": ["m_charge", "m_charge_ok", "m_charge_retry", "m_charge_retry_ok"],
"extensions": { "operator": "alt", "operands": [{ "startsAt": "m_charge_retry", "guard": "retry on 5xx" }] }
}
Any other frame in a sequence diagram is drawn by what its children hold, whatever its containerType: a participant box round lifelines, or a highlight band behind messages and notes. A frame that holds both isn’t drawn, and boxes don’t nest or overlap. The engine lays both out and ignores their layout (Rendering: Participant boxes and highlight bands).
laneDirection, on a pool, says how its lanes stack. Lanes always run along the flow and stack across it:
laneDirection | Lanes | BPMN calls it | Flow |
|---|---|---|---|
"vertical" | Stacked top to bottom | A horizontal pool | Left to right (LR, or RL when layoutStrategy.direction asks for it) |
"horizontal" | Side by side | A vertical pool | Top to bottom (TB, or BT) |
When layoutStrategy.direction runs along the lanes’ stacking ("horizontal" with LR, say), laneDirection wins and the flow turns to run across the lanes. Without laneDirection, lanes stack across the scene’s direction: top to bottom in a left-to-right flow (the default outside flowcharts and org charts), side by side in a top-to-bottom one. The first pool in document order with a laneDirection sets the flow for the whole diagram. Lanes along the flow, such as phases or milestones, aren’t supported.
Spanning frames
A frame written with spans instead of children is drawn round the nodes and frames it names, outside the containment tree: an Auto Scaling group or a security group across Availability Zones, or a Google Cloud VPC across Regions. Each target keeps its own frame, so its membership doesn’t change.
{ "id": "asg", "kind": "frame", "containerType": "aws.autoScalingGroup", "title": "Auto Scaling group", "spans": ["private_a", "private_b"] }
A Google Cloud zone is a spanning frame drawn as a strip under each node it spans instead of a box round them (Rendering: Google Cloud groups):
{ "id": "zone_b", "kind": "frame", "containerType": "gcp.zone", "title": "Zone b", "spans": ["web_2", "app_2", "db_primary"] }
A spanning frame holds nothing: give a frame spans or children, not both. Its targets are nodes and frames other than spanning frames, so spanning frames don’t nest; no frame or group lists it, and its layout is ignored. A target that doesn’t exist is SPAN_TARGET_NOT_FOUND, and a break of the other rules is SPAN_INVALID. Layout Engine: Spanning frames has the families that draw it, its box, the room kept for it and what it doesn’t do.
Text
A standalone text block: a title, caption, legend or note. An edit adds one with createText, and setText changes its words and textStyle. Its textStyle defaults to one line per \n at the box’s top left (wrap: "none", align: "left", verticalAlign: "top").
{
"id": "text-1",
"kind": "text",
"text": "System Architecture",
"layout": {
"mode": "absolute",
"x": 50, "y": 20,
"width": 300, "height": 40
}
}
A text with an absolute layout stays where you write it. The engine keeps a new diagram’s nodes clear of it. Three cases are the exception: a sequence diagram, a diagram with a pool or lane that has a layout of its own, and nodes you gave positions (Layout engine: What auto-layout handles and what it doesn’t).
text elements support textStyle.wrap: "word" for line-wrapped paragraphs ("character" also breaks a word wider than the element, and "auto" wraps only when the text is wider than the element; where lines break) and accept \n for explicit line breaks. For bullet lists, embed unicode bullets directly: "text": "Features:\n• Fast\n• Reliable\n• Cheap".
Example: titles, dividers, and dashed edges. Use text for section titles and callouts (OUTSIDE a node), guide (see Guide below) for canvas-spanning dashed separators, and style.dash on edges for dashed connectors. Three primitives composing into one annotated architecture:
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"layoutStrategy": { "direction": "LR" },
"scene": {
"id": "annotated",
"title": "Annotated Architecture",
"canvas": { "width": 900, "height": 420 }
},
"elements": [
{
"id": "title",
"kind": "text",
"text": "Payment Processing Flow",
"layout": { "mode": "absolute", "x": 20, "y": 10, "width": 500, "height": 30 },
"textStyle": { "align": "left" },
"style": { "fontSize": 18, "textColor": "#1a1a1a" }
},
{
"id": "divider",
"kind": "guide",
"orientation": "horizontal",
"position": 50
},
{ "id": "client", "kind": "node", "nodeType": "actor", "shape": "roundedRect", "label": "Client" },
{ "id": "checkout", "kind": "node", "nodeType": "service", "shape": "roundedRect", "label": "Checkout" },
{ "id": "processor", "kind": "node", "nodeType": "externalSystem", "shape": "cloud", "label": "Stripe" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "client" }, "to": { "elementId": "checkout" }, "label": "submit" },
{ "id": "e2", "kind": "edge", "from": { "elementId": "checkout" }, "to": { "elementId": "processor" }, "label": "charge", "style": { "dash": [4, 4], "stroke": "#cc6600" } }
]
}
style.dash takes a number array ([4, 4], [6, 3], [2, 2]) for dashed strokes. Works on edges and on element strokes.
Image
An image element shows an entry of the scene’s assets; an edit adds one with createImage, after updateScene adds its asset. Use a data: URI for the asset; a remote one gets a warning. An image with an absolute layout stays where you write it, and the engine keeps nodes clear of it as it does of a text, with the same three exceptions (Layout engine: What auto-layout handles and what it doesn’t).
{
"id": "img-1",
"kind": "image",
"assetRef": "logo",
"layout": {
"mode": "absolute",
"x": 50, "y": 50,
"width": 200, "height": 100
}
}
Guide
An alignment guide (horizontal or vertical line).
{
"id": "guide-1",
"kind": "guide",
"orientation": "horizontal",
"position": 200
}