Complete syntax reference for the Datro DSL (.dtro files). Every block type, every field, every diagnostic code — all in one place.

Every .dtro file must begin with the magic header on line 1. The parser returns E100 if it is missing or malformed.

#!DATRO 1.0

Optional document-level metadata. Produces I003 info hint if omitted. All fields are optional strings/arrays except kind.

#!DATRO 1.0

meta {
  title:       "Payment Service"
  version:     "2.1.0"
  description: "Handles card and crypto charges"
  author:      "jane@example.com"
  owner:       "payments-team"
  tags:        ["payments", "critical"]
  sla:         "99.95%"
  criticality: "P0"
  kind:        architecture
}

Declares an entity in the diagram. Each node has a unique id, a semantic type that controls its rendered shape and default colour, and an optional attrs block for metadata.

# Minimal
node api_gw { type: gateway label: "API Gateway" }

# With attrs block
node payment_svc {
  type:  service
  label: "Payment Service"
  attrs {
    tech:       "nestjs"
    owner:      "payments-team"
    deprecated: false
    sla:        "99.95%"
  }
}

# Inline attrs (alternative syntax)
node db { type: database label: "Payments DB"  attrs { tech: "postgres" } }

Declares a relationship between two nodes. Edge direction is written directly in the declaration: -> (directed), <-> (bidirectional), or -- (undirected).

# Minimal
edge api_gw -> payment_svc { kind: http }

# Full metadata
edge payment_svc -> stripe {
  kind:   http
  label:  "charge API"
  weight: 2.0
  async:  false
  attrs { sla: "200ms" }
}

# Bidirectional edge
edge cache <-> service { kind: read }

# Undirected edge
edge svc_a -- svc_b { kind: depends }

Clusters related nodes into a labelled subgraph box. A node may belong to at most one group — E403 fires on conflicts. Groups can be nested: a member id may reference another group id.

group data_tier {
  label:   "Data Layer"
  members: [payments_db, fraud_cache, audit_log]
  attrs { compliance: "PCI-DSS" }
}

# Alternative: assign group on the node
node payments_db {
  type:  database
  label: "Payments DB"
  group: data_tier
}

Declares an architectural rule that the validator evaluates against the IR. Violations produce E501 (or W501 when severity: warn). The rule field uses a concise three-token grammar.

# Prohibition: databases may not call external services
constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect directly to external APIs"
  severity: error
}

# Requirement: every gateway must connect to a service
constraint {
  rule:     "gateway -> service"
  message:  "Each gateway must route to at least one service"
  severity: warn
}

# Membership: all databases must be in the data_tier group
constraint {
  rule:     "database in data_tier"
  message:  "All database nodes must belong to the data_tier group"
  severity: error
}

Constraint verbs

• `!->` — no SUBJECT node may have a directed edge to any OBJECT node.
• `->` — every SUBJECT node must have at least one directed edge to an OBJECT node.
• `!<->` — no bidirectional edge may exist between SUBJECT and OBJECT nodes.
• `<->` — every SUBJECT node must have a bidirectional edge to some OBJECT node.
• `in` — every SUBJECT node must be a member of the OBJECT group.
• `!in` — no SUBJECT node may be a member of the OBJECT group.

Splits large diagrams across multiple .dtro files. The resolver merges imported IR into the parent before validation. Use as for namespacing and expose to whitelist specific ids.

# Import everything from another .dtro file
import "auth.dtro"

# Import with a namespace alias — IDs become auth.user_service, etc.
import "auth.dtro" as auth

# Import only specific IDs (whitelist)
import "infra.dtro" as infra expose [load_balancer, cdn]

Hints to the renderer about how to arrange the graph. All fields are optional — the renderer uses sensible defaults when the block is omitted.

layout {
  direction:       LR          # LR | RL | TB | BT
  algo:            dagre        # dagre | dot | elk | force | none
  node_sep:        60           # px between nodes in the same rank
  rank_sep:        120          # px between ranks
  margin:          20           # graph margin in px
  cluster_padding: 16           # padding inside group boxes
}

Controls the visual appearance of the rendered diagram. The palette maps node types to hex colours. The accessibility sub-block enables automatic WCAG 2.1 contrast checking.

theme {
  name: "Corporate"

  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    gateway:    "#FFD0D0"
    queue:      "#E8D0FF"
    cache:      "#C0FFE8"
    external:   "#F0F0F0"
    background: "#FFFFFF"
  }

  typography {
    font_family:      "Inter, sans-serif"
    node_font_size:   11
    edge_font_size:   9
    label_font_weight: "600"
  }

  accessibility {
    min_contrast:    AA          # AA | AAA | none
    max_label_length: 60
  }
}

Fine-grained per-element overrides applied after the theme. Rules cascade: by_id overrides by_type. Each sub-block maps a key to a property map.

style {
  # Override by node type
  by_type {
    database { fill: "#FFF3CD"  stroke: "#E6A817"  shape: cylinder }
    external { fill: "#F8F9FA"  stroke: "#6C757D"  dash: true }
  }

  # Override individual node by id
  by_id {
    stripe { fill: "#635BFF"  stroke: "#4B44CC" }
  }

  # Style edge kinds
  by_edge_kind {
    query   { color: "#E6A817"  width: 2 }
    publish { color: "#198754"  dash: true }
  }

  # Style edges that carry a boolean attr set to true
  by_edge_attr {
    async { dash: true  color: "#ADB5BD" }
  }
}

All diagnostics include a code, severity, message, and an optional line:col location. The table below lists every code the toolchain can emit.

Errors (E×××)

• `E100` — Magic header #!DATRO 1.0 is missing or malformed
• `E201` — Duplicate node id
• `E202` — Node references an unknown group id
• `E301` — Edge from node not found
• `E302` — Edge to node not found
• `E303` — Edge weight is negative
• `E401` — Duplicate group id
• `E402` — Group members references an unknown id
• `E403` — Node is assigned to more than one group
• `E404` — Circular group nesting detected
• `E500` — Constraint rule has a syntax error
• `E501` — Constraint rule is violated (severity mirrors the constraint's own severity)

Warnings (W×××)

• `W301` — Duplicate edge (same from/to/kind/label)
• `W501` — Constraint rule uses an unknown verb
• `W601` — Node label exceeds max_label_length (default 80 chars)
• `W602` — Theme palette colour falls below WCAG AA contrast (4.5:1)
• `W603` — Theme palette colour falls below WCAG AAA contrast (7.0:1)

Info hints (I×××)

• `I001` — Isolated node — no edges connect to it
• `I002` — Empty group — no members declared
• `I003` — No meta block — recommended for documentation
• `I601` — No theme palette defined — contrast checks skipped

• Use the CLI Reference to validate, format, and export from the command line.
• Embed diagrams in Markdown with the Markdown plugin.
• Go back to Quick Start for a step-by-step walkthrough.