Language Reference

Vollständige Syntaxreferenz für die Datro DSL-Dateien (.dtro-Dateien). Jeder Blocktyp, jedes Feld, jeder Diagnosecode – alles an einem Ort.

Jede .dtro-Datei muss mit dem Magic-Header in Zeile 1 beginnen. Der Parser gibt E100 zurück, wenn er fehlt oder fehlerhaft ist.

#!DATRO 1.0

Optionale Metadaten auf Dokumentebene. Erzeugt einen I003-Infohinweis, wenn er weggelassen wird. Alle Felder außer kind sind optionale Zeichenfolgen/Arrays.

#!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
}

Deklariert eine Entität im Diagramm. Jeder Knoten hat eine eindeutige ID, einen semantischen type, der seine gerenderte Form und Standardfarbe steuert, und einen optionalen attrs-Block für Metadaten.

# 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" } }

Deklariert eine Beziehung zwischen zwei Knoten. Die Kantenrichtung wird direkt in die Deklaration geschrieben: -> (gerichtet), <-> (bidirektional) oder -- (ungerichtet).

# 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 }

Gruppiert verwandte Knoten in einem beschrifteten Unterdiagrammfeld. Ein Knoten darf höchstens einer Gruppe angehören – E403 wird bei Konflikten ausgelöst. Gruppen können verschachtelt sein: Eine Mitglieds-ID kann auf eine andere Gruppen-ID verweisen.

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
}

Deklariert eine Architekturregel, die der Validator anhand der IR auswertet. Verstöße erzeugen E501 (oder W501, wenn severity: warn). Das Feld rule verwendet eine prägnante Drei-Token-Grammatik.

# 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
}

Einschränkungsverben

• `!->` – kein SUBJECT-Knoten darf eine gerichtete Kante zu einem beliebigen OBJECT-Knoten haben.
• `->` – jeder SUBJECT-Knoten muss mindestens eine gerichtete Kante zu einem OBJECT-Knoten haben.
• `!<->` – zwischen den Knoten SUBJECT und OBJECT darf keine bidirektionale Kante vorhanden sein.
• `<->` – jeder SUBJECT-Knoten muss eine bidirektionale Kante zu einem OBJECT-Knoten haben.
• `in` – jeder SUBJECT-Knoten muss Mitglied der Gruppe OBJECT sein.
• `!in` – kein SUBJECT-Knoten darf Mitglied der Gruppe OBJECT sein.

Teilt große Diagramme auf mehrere .dtro-Dateien auf. Der Resolver führt die importierte IR vor der Validierung mit der übergeordneten IR zusammen. Verwenden Sie as für den Namensraum und expose, um bestimmte IDs auf die Whitelist zu setzen.

# 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]

Hinweise für den Renderer zur Anordnung des Diagramms. Alle Felder sind optional – der Renderer verwendet sinnvolle Standardwerte, wenn der Block weggelassen wird.

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
}

Steuert das visuelle Erscheinungsbild des gerenderten Diagramms. Der palette ordnet Knotentypen Hex-Farben zu. Der Unterblock accessibility ermöglicht die automatische WCAG 2.1-Kontrastprüfung.

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
  }
}

Fein abgestufte Überschreibungen pro Element, die nach dem Thema angewendet werden. Regelkaskade: by_id überschreibt by_type. Jeder Unterblock ordnet einen Schlüssel einer Eigenschaftszuordnung zu.

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" }
  }
}

Alle Diagnosen umfassen einen code, severity, message und einen optionalen line:col-Standort. In der folgenden Tabelle ist jeder Code aufgeführt, den die Toolchain ausgeben kann.

Fehler (E×××)

• `E100` – Der Magic-Header #!DATRO 1.0 fehlt oder ist fehlerhaft
• `E201` – Doppelte Knoten-ID
• `E202` – Knoten verweist auf eine unbekannte Gruppen-ID
• `E301` – Edge-Knoten from nicht gefunden
• `E302` – Edge-Knoten to nicht gefunden
• `E303` – Kante weight ist negativ
• `E401` – Doppelte Gruppen-ID
• `E402` – Gruppe members verweist auf eine unbekannte ID
• `E403` – Knoten ist mehr als einer Gruppe zugewiesen
• `E404` – Verschachtelung kreisförmiger Gruppen erkannt
• `E500` – Einschränkungsregel weist einen Syntaxfehler auf
• `E501` – Einschränkungsregel wird verletzt (Schweregrad spiegelt den eigenen severity der Einschränkung wider)

Warnungen (B×××)

• `W301` – Kante duplizieren (gleich von/bis/art/beschriftung)
• `W501` – Einschränkungsregel verwendet ein unbekanntes Verb
• `W601` – Knotenbezeichnung überschreitet max_label_length (Standard 80 Zeichen)
• `W602` – Die Farbe der Themenpalette liegt unter dem WCAG AA-Kontrast (4,5:1)
• `W603` – Die Farbe der Themenpalette liegt unter dem WCAG AAA-Kontrast (7,0:1)

Info-Hinweise (I×××)

• `I001` – Isolierter Knoten – keine Kanten sind mit ihm verbunden
• `I002` – Leere Gruppe – keine Mitglieder deklariert
• `I003` – Kein meta-Block – für Dokumentation empfohlen
• `I601` – Keine Themenpalette definiert – Kontrastprüfungen übersprungen

• Verwenden Sie CLI Reference zum Validieren, Formatieren und Exportieren über die Befehlszeile.
• Betten Sie Diagramme in Markdown mit dem Markdown plugin ein.
• Gehen Sie zurück zu Quick Start für eine Schritt-für-Schritt-Anleitung.