DSL Reference

The tokenizer recognises keywords, identifiers, double-quoted strings, integers, arrows (->), braces, and structural punctuation. Whitespace is insignificant except that newlines terminate statements within a block.

• / Comments start with # and run to end of line.
• / Strings use double quotes; \n, \t, and \" are recognised escapes.
• / Identifiers match [a-zA-Z_][a-zA-Z0-9_\-/.]* — hyphens, slashes, and dots are legal mid-identifier, which is what allows icon paths like aws/lambda to parse as a single token.
• / Reserved keywords: diagram, zone, node, connect, note, color, icon, label, style, pinned, bidirectional, sequence, participant, actor, message, entity, field, relation, process, datastore, flow, system, container, component, decision, start, end, network, subnet, device.
• / Errors are raised as ParseError with line and column; semantic checks (e.g. unknown connection target) run in a separate validate pass.

Shared values

• Colors: blue, teal, purple, green, amber, coral, pink, gray, red.
• Edge styles: solid, dashed, dotted.

Top-level form: diagram "Title" { ... }. Body items are zone, node, and connect. Zones may nest other zones and nodes; nodes accept an optional icon and a pinned flag.

diagram "Checkout architecture" {
  zone "Edge" color blue {
    node cdn "CloudFront" icon aws/cloudfront
  }

  zone "VPC" color teal {
    node api "API Gateway" icon aws/api-gateway
    node svc "Checkout Service" icon aws/lambda pinned

    zone "Private subnet" color gray {
      node db "Orders DB" icon aws/rds
      node cache "Session cache" icon aws/elasticache
    }
  }

  connect cdn -> api "HTTPS"
  connect api -> svc "invoke"
  connect svc -> db "SQL" style solid
  connect svc -> cache "TCP" bidirectional
}

Top-level keyword is sequence. Body items are participant, actor, message, and note.

sequence "Login" {
  actor user "End user"
  participant web "Web app"
  participant api "API"
  participant auth "Auth service"

  message user -> web "submits credentials"
  message web -> api "POST /login"
  message api -> auth "validate" style dashed
  message auth -> api "jwt"
  message api -> web "200 OK"
  note web "token cached in memory only"
}

Top-level keyword is diagram. Body items are entity blocks and relation statements.

diagram "Commerce schema" {
  entity User {
    field id "uuid" pk
    field email "varchar(320)" unique
    field created_at "timestamptz"
  }

  entity Order {
    field id "uuid" pk
    field user_id "uuid" fk
    field total "numeric(12,2)"
    field notes "text" nullable
  }

  relation User -> Order "1:N" label "places"
}

Top-level keyword is diagram. Body items are process, datastore, actor, and flow. Useful for DFDs and threat-modelling sketches.

diagram "Order processing" {
  actor customer "Customer"
  process order-api "Order API" icon aws/lambda
  process payment "Payment service"
  datastore orders-db "Orders" icon aws/dynamodb

  flow customer -> order-api "place order"
  flow order-api -> orders-db "write"
  flow order-api -> payment "charge" style dashed
}

Top-level keyword is diagram. Body items are system and connect. A system either has a brace-delimited body of container declarations, or a single optional description string for an external system.

diagram "E-commerce platform" {
  system shop "Shop" {
    container web "Web app" "React SPA" icon generic/browser
    container api "API" "Node.js / Fastify"
    container db  "Database" "PostgreSQL" icon generic/database
  }

  system stripe "Stripe" "External payments API"

  connect web -> api "REST/JSON" style solid
  connect api -> db "SQL/TCP"
  connect api -> stripe "HTTPS"
}

Top-level keyword is diagram. Nodes are declared by their type keyword: start, end, process, or decision. Edges use connect with optional label and style attributes (note: in flowcharts the label keyword is required, unlike cloud-arch where the bare string is accepted).

diagram "Release pipeline" {
  start begin "Push to main"
  process lint "Lint and typecheck"
  decision tests "Tests pass?"
  process build "Build image"
  process deploy "Deploy to prod"
  end done "Live"

  connect begin -> lint
  connect lint -> tests
  connect tests -> build label "yes"
  connect tests -> begin label "no" style dashed
  connect build -> deploy
  connect deploy -> done
}

Top-level keyword is diagram. Body items are network blocks and connect statements. A network may contain subnet blocks and bare device declarations; subnets contain only devices.

diagram "Office network" {
  network wan "WAN" {
    device isp "ISP router" icon generic/router
  }

  network lan "Corporate LAN" color blue {
    subnet dmz "DMZ" color amber {
      device fw  "Firewall"   icon generic/firewall
      device web "Web server" icon generic/server
    }

    subnet internal "Internal" color teal {
      device app "App server" icon generic/server
      device db  "DB server"  icon generic/database
    }
  }

  connect isp -> fw  "WAN link"
  connect fw  -> web "HTTP"
  connect fw  -> app "Trunk" style dashed
  connect app -> db  "SQL"
}

The icon attribute takes an identifier path of the form provider/name, e.g. aws/lambda, azure/blob, gcp/cloud-run, or generic/database. The parser does not validate that the icon exists; the renderer falls back to a neutral glyph if the path is unknown.

Each diagram type ships a separate validate* function that runs after parsing and reports semantic problems — the most common is a connect, flow, or message that references an id which was never declared. Validation errors do not throw; they are returned as a list so the editor can surface multiple problems at once.