Skip to content

The model ​

Everything umlimator draws comes from one JSON file, the model. A model holds shared nodes (cards) and edges (lines), and views that each show a subset of them. The same card can appear in several views, and a card can open another view, which is how a map gets its layers.

json
{
  "$schema": "./node_modules/umlimator/lib/umlimator.schema.json",
  "title": "Bookshop",
  "nodes": [
    { "id": "web", "label": "Web shop", "kind": "frontend" },
    { "id": "api", "label": "Orders API", "kind": "backend", "opensView": "api" },
    { "id": "db", "label": "Orders", "kind": "database" }
  ],
  "edges": [
    { "id": "e1", "from": "web", "to": "api", "label": "places orders" },
    { "id": "e2", "from": "api", "to": "db", "label": "writes", "kind": "state" }
  ],
  "views": [
    { "id": "overview", "parent": null, "title": "Bookshop", "nodeIds": ["web", "api", "db"] }
  ]
}

A view may also have containers (boxes), a layout ([col, row] per card), render: "sequence" for a numbered run-order view and a tour, a dot that rides a path. Views and layers covers them. The full map schema is engine/references/schema.md (§ Map model); examples/umlimator-atlas.json, umlimator's own model, uses much of it.

Schema and validation ​

A model file that starts with "$schema": "<path to>/umlimator.schema.json" (exported as umlimator/schema.json) gets completion and checks in editors. validate(model) lists its errors and warnings, each with where it is, and rules(model) lists every rule the model breaks, view by view.

Maps and typed diagrams ​

A model with no schemaVersion is a map, as always. "schemaVersion": 2 marks a model that may hold typed elements and typed views (docs/diagrams/model.md); a version newer than the module reads is an error. A view's diagram says which of the 28 diagram types it is:

Familydiagram valuesSince
UML structure"uml.class", "uml.object", "uml.package", "uml.component", "uml.deployment", "uml.composite-structure", "uml.profile"0.18.0 to 0.23.0
UML behaviour"uml.sequence", "uml.communication", "uml.use-case", "uml.activity", "uml.state-machine", "uml.interaction-overview", "uml.timing", "uml.information-flow"0.20.0 to 0.24.0
Data and process"er" (entity-relationship), "flowchart", "dfd" (data flow)0.24.0
C4"c4.landscape", "c4.context", "c4.container", "c4.component", "c4.dynamic", "c4.deployment"0.24.0
SysML v1.7"sysml.requirement", "sysml.block-definition", "sysml.internal-block", "sysml.parametric"0.25.0
Mindmap and cloud"mindmap", and "gcp", "azure" and "aws" for Google Cloud, Azure and AWS architecture diagrams0.26.0
BPMN"bpmn"0.27.0

Each is drawn by umlimator/all and the CLI. umlimator alone draws maps, and shows a typed view's nodes as plain cards, with a warning. Each type's note in docs/conformance/ says what it covers and lists every field.

Map fields ​

Card kinds: frontend, backend, ai, database, queue, security, cloud, external and file (skill-map kinds such as public, lane, script, hook and board work too). Fields beyond the schema:

OnFieldWhat it does
nodebadges (badge)tabs on the card, each a string or { text, tone }
nodeicona logo or line icon from icons/manifest.json
nodenoSubthe name only; the description stays in the details panel
nodeopensView, opensCountthe view the card opens, which may not be loaded yet, and the ⤢ number for it
nodeownerwho owns the card (a team): rules and lenses pick by it, and a lens can ring cards by owner
nodeshapethe card's own shape, over the one its kind draws: box, person, browser, mobile, cylinder, pipe, document, hexagon, robot, terminal, window, folder or node
node, edgeediteda marker on the card or line
edgekindwhat the line means, drawn as its colour: calls (default), feeds, triggers, state, guard
edgeweight1, 2 or 3: how much the line stands for. Every line is drawn thin at rest; a line of weight 2 or 3 grows to its width (and a larger arrowhead) on hover, when its card is selected and when it has keyboard focus, and its tooltip and accessible name say its what, else "weight 2 of 3"
edgestepa number (2, or 2.1) or text of up to 3 characters (2a), in a circle on the line in any view (a pill for 2 or 3 characters): the order things happen, shown as written in the line's name and title. A numbered view numbers its lines in run order instead
edgesublabela second, smaller line under the label
edgefromSide, toSidethe card sides the line uses
edgefrom, tomay name a container of the view: the line ends on its box
edgestyle: "faded"the line in its kind's colour, faint and with no flow (drift's idle lines)
edgedriftwhat drift() found: undrawn or idle
edgelatency, costbudgets, in ms and in any unit: critical() sums them along a path (not drawn)
viewgap, rgapthe space between columns and between rows
viewkeepPairsA→B and B→A drawn as two lines
viewrepair: falseno port repair (a map view; a typed view's lines are never port-repaired)
viewsubAndChipscards 80 px tall that show their sub-line, then their chips
viewkindsFromLabelsa line whose edges name no kind takes one guessed from its label
containerbadgestabs on the box's border
containertonea palette name, as a badge's: the region behind the box tinted in it, its border dashed and its title in the tone
modelruleswhat must hold: no line from some cards to others (picked by id, kind, box or owner), or noCycles between boxes
modelstorieswalk-throughs: steps that each set the view, camera, selection, highlight, tour and caption
modellensesways to look at the map: what pick picks (by id, kind, box, owner or line kind) lit, the rest dimmed; color: "owner" rings cards by owner

Typed diagram fields ​

The tables below list the fields each family of diagram types adds in a version-2 model. Each type's conformance note has the complete list and the rules that check them.

Class, object and package diagrams (0.18.0, 0.19.0) ​

In a version-2 model, a class diagram (examples/sales-classes.json; every field in docs/conformance/uml-class.md), an object diagram (examples/order-objects.json, uml-object.md) and a package diagram (examples/bookshop-packages.json, uml-package.md):

OnFieldWhat it does
node, member, edgetypewhat it is: uml.Class, uml.Interface, uml.Enumeration, uml.DataType, uml.PrimitiveType, uml.Package, uml.Comment; members uml.Property, uml.Operation, uml.EnumerationLiteral; lines uml.Association, uml.Generalization, uml.InterfaceRealization, uml.Dependency, uml.CommentLink
nodemembersits attributes, operations or literals, in order, each { id, type, label, props }
node, member, edgetype, from 0.19.0an object diagram's uml.InstanceSpecification, its members uml.Slot, lines uml.Link; a package diagram's uml.Package and the classifiers above, lines uml.PackageImport, uml.PackageMerge, uml.Dependency
nodeparentthe package that owns it: from 0.19.0 drawn as a box holding it when the view shows both
node, member, edgeprops, from 0.19.0an instance's classifier (a name, as text); a slot's value; a link's association and its ends' role; a package import's visibility, public («import») or private («access»)
node, member, edgepropsthe type's own fields: isAbstract, stereotypes; a member's visibility, valueType, multiplicity, default, isStatic, isDerived, parameters, returnType; an association's ends.from and ends.to (role, multiplicity, aggregation, navigable)
viewdiagram"uml.class", "uml.object" or "uml.package": the view is a class, object or package diagram
viewsubjectthe package the view shows the inside of: names are qualified from it
viewdirection"down" lays it out top to bottom, the general class above (default "right")
viewpresentper element: collapsed compartments, and at most rows rows each, then "+k more"

Sequence and communication diagrams (0.20.0) ​

A sequence diagram (examples/checkout-sequence.json, docs/conformance/uml-sequence.md) and a communication diagram (examples/checkout-communication.json, docs/conformance/uml-communication.md), from 0.20.0:

OnFieldWhat it does
nodetypeuml.Lifeline; its props.represents is what it is an instance of, drawn name : Type
edgetypeuml.Message; on a communication view also uml.Connector, the link messages are sent along
edgepropsa message's sort (call, async, reply, create, delete) and a reply's replyTo, the call it answers
viewdiagram"uml.sequence" or "uml.communication"
viewedgesa sequence view's messages and interaction uses (uml.InteractionUse, props.covers), inline and in time order; a communication view's connectors, then its messages, by id, in order. Bars and numbers are derived
viewfragmentsa sequence view's combined fragments (uml.CombinedFragment, props.operator), each with its operands as members (label the guard); a message's or fragment's parent is its operand

Use case, activity, state machine and interaction overview diagrams (0.21.0) ​

A use case diagram, an activity diagram, a state machine diagram and an interaction overview diagram (examples/shopping-use-cases.json, fulfil-activity.json, order-states.json and buy-book-overview.json; each type's note in docs/conformance/), from 0.21.0:

OnFieldWhat it does
node, member, edgetypeuse case: uml.Actor, uml.UseCase (members uml.ExtensionPoint), uml.Subject; lines uml.Association, uml.Include, uml.Extend, uml.Generalization
node, edgetypeactivity: uml.Action, uml.CallBehaviorAction, uml.SendSignalAction, uml.AcceptEventAction, uml.ObjectNode, uml.DataStoreNode, uml.InitialNode, uml.ActivityFinalNode, uml.FlowFinalNode, uml.DecisionNode, uml.MergeNode, uml.ForkNode, uml.JoinNode, uml.ActivityPartition; lines uml.ControlFlow, uml.ObjectFlow
node, member, edgetypestate machine: uml.State (members uml.Region, uml.InternalTransition), uml.Pseudostate, uml.FinalState; lines uml.Transition
node, edgetypeinteraction overview: the activity's control nodes, uml.InteractionUse, uml.Interaction (an inline interaction); lines uml.ControlFlow
nodeparenta use case's subject; an activity node's partition (its lane), a partition's enclosing partition; a substate's state or region
nodeopensViewthe activity a call behaviour action calls; the sequence view an interaction use or inline interaction shows
nodepropsa state's entry, do, exit; a pseudostate's kind (initial, choice, junction, fork, join, shallowHistory, deepHistory, terminate)
edge, memberpropsan extend's extensionPoints (ids) and condition; a flow's guard (its label is its name); a transition's or internal transition's trigger, guard and effect, drawn trigger [guard] / effect
viewdiagram"uml.use-case", "uml.activity", "uml.state-machine" or "uml.interaction-overview"

Component, deployment and composite structure diagrams (0.22.0) ​

A component diagram, a deployment diagram and a composite structure diagram (examples/bookshop-components.json, bookshop-deployment.json and order-service-structure.json; each type's note in docs/conformance/), from 0.22.0:

OnFieldWhat it does
node, member, edgetypecomponent: uml.Component (members uml.Port), uml.Interface, uml.Artifact, uml.Package; lines uml.InterfaceRealization, uml.Usage, uml.ComponentRealization, uml.Connector, uml.Dependency, uml.Manifestation
node, edgetypedeployment: uml.Node, uml.Device, uml.ExecutionEnvironment, uml.Artifact, uml.DeploymentSpecification, uml.Component; lines uml.Deployment, uml.Manifestation, uml.CommunicationPath, uml.Dependency
node, member, edgetypecomposite structure: the subject (uml.Class, uml.Component or uml.Collaboration) with its parts (uml.Property) and ports (uml.Port), uml.Collaboration (its roles uml.Property), uml.CollaborationUse; lines uml.Connector, uml.RoleBinding (its label the role)
nodeparenta component's component or package; an artifact's target (deployed by nesting); a target's target (any depth); a collaboration use's subject
node, memberpropsa port's valueType; a part's valueType (the class or component whose ports it shows, by label), multiplicity and aggregation (shared is dashed); a collaboration use's collaboration
edgepropsa connector's kind (assembly, delegation); an end through a part, ends.from.part or ends.to.part (UML's partWithPort)
viewsubjecta composite structure view's class, component or collaboration, listed in nodeIds
viewpresentan interface drawn as a ball ({ "as": "ball" }); a port's side ({ "side": "left" }); on a part, { "ports": { "<port>": { "side": "top" } } }
viewdiagram"uml.component", "uml.deployment" or "uml.composite-structure"

Profile and timing diagrams (0.23.0) ​

A profile diagram and a timing diagram (examples/bookshop-profile.json and bookshop-timing.json; each type's note in docs/conformance/), from 0.23.0:

OnFieldWhat it does
node, member, edgetypeprofile: uml.Profile, uml.Stereotype (members uml.Property, its tag definitions), uml.MetaclassReference (its label a UML metaclass: Class, Property, Classifier, …), uml.Enumeration (a tag's type); lines uml.Extension, uml.ProfileApplication (from a package), uml.Generalization
nodeparenta stereotype's or metaclass reference's profile; an enumeration's may be one
node, member, edgepropson any UML element, stereotypes (a name, or Profile::name where two applied profiles share it) and tags, by stereotype then tag, each value as text: { "column": { "name": "placed_at" } }; a stereotype's isAbstract; an extension's isRequired (the tool applies the stereotype to every element of that metaclass where the profile is applied)
node, edgetypetiming: uml.Lifeline (props.states, top to bottom); uml.Message inline in the view's edges, with props.sentAt and props.receivedAt (numbers) and sort call, async or reply
viewtimelineunit (optional); changes, [{ id, lifeline, at, state }] in any order (drawn by at); constraints, [{ id, type: "uml.DurationConstraint" | "uml.TimeConstraint", from, to, label }], whose ends are changes
viewpresenta lifeline drawn as a value lifeline ({ "as": "values" })
viewdiagram"uml.profile" or "uml.timing"

ER, flowchart, data flow, information flow and C4 (0.24.0) ​

Milestone 2's five types (examples/bookshop-schema.json, returns-flowchart.json, bookshop-data-flow.json, order-information-flow.json and bookshop-c4.json; each type's note in docs/conformance/), from 0.24.0:

OnFieldWhat it does
node, member, edgetypeER: er.Entity (members er.Column), lines er.Relationship from the referenced entity to the referring one. Flowchart: flow.Terminator, flow.Process, flow.Decision, flow.InputOutput, flow.PredefinedProcess, flow.Document, flow.Database, flow.ManualInput, flow.Delay, flow.Connector; lines flow.Flow. Data flow: dfd.Process, dfd.DataStore, dfd.ExternalEntity; lines dfd.DataFlow. Information flow: uml.InformationItem and the classes, interfaces, components and actors it travels between; lines uml.InformationFlow. C4: c4.Person, c4.SoftwareSystem, c4.Container, c4.Component, c4.DeploymentNode, c4.ContainerInstance; lines c4.Relationship (its label the description)
memberpropsa column's dataType, primaryKey, foreignKey, references (a column id), nullable, unique
node, edgepropsa relationship's identifying and ends.from and ends.to's multiplicity; a process's or store's number; a flow's conveyed (ids); a C4 element's description, technology, external, shape (a map card shape other than node, which is the deployment view's: box, person, robot, browser, window, terminal, mobile, cylinder, pipe, folder, document or hexagon; any other name draws the default, person for a person and box for the rest), an instance's container; a C4 relationship's technology
nodeparenta container's software system, a component's container, a deployment node's node, an instance's node
nodeopensViewa process's level: a dfd view whose parent is the view the process is on
viewnotation"crowsfoot" (default) or "idef1x" for er, "yourdon" (default) or "gane-sarson" for dfd: a repaint
viewsubjecta C4 view's system or container, drawn as a boundary when nodeIds lists it
viewedgesa C4 dynamic view's steps: relationship ids, each once, in time order
viewdiagram"er", "flowchart", "dfd", "uml.information-flow", "c4.landscape", "c4.context", "c4.container", "c4.component", "c4.dynamic", "c4.deployment"

SysML v1.7 (0.25.0) ​

SysML v1.7's four types (examples/ebike-requirements.json, ebike-blocks.json, ebike-structure.json and ebike-range.json; each type's note in docs/conformance/), from 0.25.0:

OnFieldWhat it does
node, member, edgetypeRequirement: sysml.Requirement, sysml.TestCase, sysml.Block, uml.Package; lines sysml.DeriveReqt, sysml.Satisfy, sysml.Verify, sysml.Refine, sysml.Trace, sysml.Copy, client to supplier. Block definition: sysml.Block, sysml.InterfaceBlock, sysml.ConstraintBlock, sysml.ValueType; members sysml.PartProperty, sysml.ReferenceProperty, sysml.ValueProperty, sysml.ConstraintProperty, sysml.Port, sysml.FlowProperty, sysml.ConstraintParameter, uml.Operation; the class diagram's lines. Internal block: lines sysml.Connector. Parametric: lines sysml.BindingConnector
nodepropsa requirement's reqId, text, risk, verifyMethod; a constraint block's constraint; a value type's unit, quantityKind
memberpropsvalueType (a port's starting ~ is conjugated), multiplicity, default; a port's kind (proxy, full); a flow property's direction
edgepropsa connector's itemFlow ({ item, direction }); a connector's or binding's ends.<from|to>.part
nodeparenta requirement's owner, a requirement (drawn as a crosshair line) or a package
viewsubjectthe frame's element: a package (requirement, block definition), a block (internal block, parametric) or a constraint block (parametric)
viewdiagram"sysml.requirement", "sysml.block-definition", "sysml.internal-block", "sysml.parametric"

Mindmap, Google Cloud, Azure and AWS (0.26.0) ​

The mindmap and the three cloud architecture types (examples/bookshop-opening-plan.json, bookshop-gcp.json, bookshop-azure.json and bookshop-aws.json; mindmap.md, gcp.md, azure.md, aws.md), from 0.26.0:

OnFieldWhat it does
node, edgetypemindmap: mindmap.Topic, no lines. Google Cloud: gcp.Zone (a group), gcp.Product, gcp.User; lines gcp.Path. Azure: azure.Group, azure.Service; lines azure.Connector. AWS: aws.Group, aws.Service, aws.Resource; lines aws.Connection. A cloud line may start or end at a group, never join a group and what it holds
nodeparenta topic's parent topic (a topic with none is a root); the group that holds a group or a service
nodepropsa group's kind, zoneType (project, region, zone, network, subnetwork, generic) or groupType (subscription, resource-group, region, virtual-network, subnet, generic), or on AWS groupType (cloud, account, region, availability-zone, vpc, public-subnet, private-subnet, security-group, generic); a product's or service's icon, the pinned pack's own id (Cloud-Run, Front-Door-and-CDN-Profiles)
modeliconsfrom the CLI or a host: <pack>/<id> with { src, dark, name }, and Google's gcp/ with { legal }; the module never fetches one
modeliconPacksthe label of the pin each pack's ids were chosen from ({ "gcp": "2026-11-14" }); umlimator.py check compares it with the release's
viewpresenta first-level topic's half: { "side": "left" }
viewdiagram"mindmap", "gcp", "azure", "aws"

BPMN (0.27.0) ​

A BPMN diagram (examples/bookshop-order-to-shipment.json; docs/conformance/bpmn.md), from 0.27.0:

OnFieldWhat it does
node, member, edgetypebpmn.Participant (a pool; members bpmn.Lane), bpmn.Task, bpmn.SubProcess, bpmn.CallActivity, bpmn.StartEvent, bpmn.EndEvent, bpmn.IntermediateCatchEvent, bpmn.IntermediateThrowEvent, bpmn.BoundaryEvent, bpmn.ExclusiveGateway, bpmn.ParallelGateway, bpmn.DataObject, bpmn.DataStoreReference, bpmn.TextAnnotation, bpmn.Group; lines bpmn.SequenceFlow, bpmn.MessageFlow, bpmn.Association, bpmn.DataAssociation (a flow's label is its name)
member, nodeparenta lane's lane of the same pool (nested); a flow node's innermost lane, its pool, its sub-process or none; data's pool or none
node, edgepropson any element, documentation; a pool's processRef; a task's taskType (none, user, service); an event's definition (none, message, timer, terminate, by its kind); a boundary event's attachedTo (an activity) and cancelActivity (false: non-interrupting); a call activity's calledElement; a data store's dataStoreRef; the groups an element is in, categoryValueRef (ids); an association's direction (none, one, both)
nodeopensViewa collapsed sub-process's own view, whose subject is the sub-process
viewpresenta boundary event's side ({ "side": "bottom" })
viewdiagram"bpmn"; a sub-process is drawn expanded when nodeIds lists something it holds