New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

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:

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:

UseKeys
Edge and DNSaws:route53, aws:cloudfront, aws:waf, aws:shield, aws:api-gateway
Networkaws: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
Computeaws:ec2, aws:ec2-instance, aws:lambda, aws:ecs, aws:ecs-service, aws:ecs-task, aws:eks, aws:fargate, aws:auto-scaling
Dataaws:rds, aws:aurora, aws:dynamodb, aws:elasticache, aws:s3, aws:s3-bucket, aws:efs, aws:redshift, aws:opensearch-service
Integrationaws:sqs, aws:sns, aws:eventbridge, aws:step-functions, aws:kinesis
Security and operationsaws:iam, aws:cognito, aws:kms, aws:secrets-manager, aws:cloudwatch, aws:cloudtrail
People and placesaws: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:

UseKeys
Edge and DNSgcp:cloud-load-balancing, gcp:cloud-armor, gcp:cloud-cdn, gcp:cloud-dns, gcp:apigee
Networkgcp:vpc, gcp:cloud-nat, gcp:cloud-router, gcp:cloud-vpn, gcp:cloud-interconnect
Computegcp:compute-engine, gcp:gke, gcp:cloud-run, gcp:cloud-run-functions, gcp:app-engine
Datagcp:cloud-sql, gcp:alloydb, gcp:spanner, gcp:firestore, gcp:bigtable, gcp:memorystore, gcp:cloud-storage, gcp:bigquery
Integrationgcp:pubsub, gcp:eventarc, gcp:workflows, gcp:cloud-tasks, gcp:cloud-scheduler, gcp:dataflow
Security and operationsgcp:identity-and-access-management, gcp:secret-manager, gcp:key-management-service, gcp:cloud-logging, gcp:cloud-monitoring
People and placesgcp: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

ShapeDescription
rectRectangle
roundedRectRounded rectangle
ellipseEllipse / circle
diamondDiamond / rhombus
cylinderDatabase cylinder
bucketObject-storage bucket
pillPill / stadium
hexagonHexagon
parallelogramParallelogram (input and output)
cloudCloud shape
box3dIsometric 3D box
textBoxText container (renders as rect)
iconBoxIcon container (renders as rect)
documentDocument: a box with a wavy bottom, the label above the wave
subroutinePredefined 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:

nodeTypeDefault shape
er.entity, er.weakEntityrect
er.attributeellipse
er.relationshipdiamond
workflow.task, workflow.subprocessroundedRect
workflow.start, workflow.end, workflow.timer, workflow.error, workflow.intermediate*, workflow.terminate, workflow.message*ellipse
workflow.gateway*, workflow.decisiondiamond
service, actor, queue, externalSystem, process, org.person, org.role, uiflow.screen, uiflow.modalroundedRect
database, storagecylinder
objectStoragebucket
event, uiflow.entry, uiflow.exitellipse
network.cloudcloud
iconNodeiconBox
decisiondiamond
documentdocument
Any other / unknownrect

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 metadataInferred cardinality
The only PK column (pk: true or key: "PK")one
One of several PK columnsmany
FK column, unique + nullable: truezero-or-one
FK column, uniqueone
FK column, nullable: truezero-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 typeThe participant is
sequence.boundaryAn interface to the outside
sequence.controlLogic that coordinates
sequence.entityA domain object
sequence.databaseA database
sequence.collectionsMany of one thing
sequence.queueA 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.

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).

PropertyValuesDefaultDescription
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):

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:

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:

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:

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:

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:

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

RouterDescription
straightOne line between centers, ending on each outline
orthogonalRight-angle connectors
curvedOne bowed arc, ending on each outline
polylineRight-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:

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:

wrapA 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 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:

ValueMarkerDescription
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.

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.

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:

laneDirectionLanesBPMN calls itFlow
"vertical"Stacked top to bottomA horizontal poolLeft to right (LR, or RL when layoutStrategy.direction asks for it)
"horizontal"Side by sideA vertical poolTop 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
}