Language Reference

Référence de syntaxe complète pour le Datro DSL (fichiers .dtro). Chaque type de bloc, chaque champ, chaque code de diagnostic, le tout au même endroit.

Chaque fichier .dtro doit commencer par l'en-tête magique de la ligne 1. L'analyseur renvoie E100 s'il est manquant ou mal formé.

#!DATRO 1.0

Métadonnées facultatives au niveau du document. Produit un indice d'information I003 en cas d'omission. Tous les champs sont des chaînes/tableaux facultatifs, sauf 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
}

Déclare une entité dans le diagramme. Chaque nœud a un identifiant unique, un type sémantique qui contrôle sa forme rendue et sa couleur par défaut, et un bloc attrs facultatif pour les métadonnées.

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

Déclare une relation entre deux nœuds. La direction du bord est écrite directement dans la déclaration : -> (dirigé), <-> (bidirectionnel) ou -- (non orienté).

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

Regroupe les nœuds associés dans une boîte de sous-graphique étiquetée. Un nœud peut appartenir à au plus un groupe — E403 se déclenche en cas de conflits. Les groupes peuvent être imbriqués : un identifiant de membre peut faire référence à un autre identifiant de groupe.

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
}

Déclare une règle architecturale que le validateur évalue par rapport à l'IR. Les violations produisent E501 (ou W501 lorsque severity: warn). Le champ rule utilise une grammaire concise à trois jetons.

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

Verbes de contrainte

• `!->` — aucun nœud SUBJECT ne peut avoir un bord dirigé vers un nœud OBJECT.
• `->` — chaque nœud SUBJECT doit avoir au moins un bord dirigé vers un nœud OBJECT.
• `!<->` — aucun bord bidirectionnel ne peut exister entre les nœuds SUBJECT et OBJECT.
• `<->` — chaque nœud SUBJECT doit avoir un bord bidirectionnel vers un nœud OBJECT.
• `in` — chaque nœud SUBJECT doit être membre du groupe OBJECT.
• `!in` — aucun nœud SUBJECT ne peut être membre du groupe OBJECT.

Divise les grands diagrammes sur plusieurs fichiers .dtro. Le résolveur fusionne l'IR importé dans le parent avant la validation. Utilisez as pour l'espacement des noms et expose pour ajouter des identifiants spécifiques à la liste blanche.

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

Conseils au moteur de rendu sur la manière d'organiser le graphique. Tous les champs sont facultatifs — le moteur de rendu utilise des valeurs par défaut raisonnables lorsque le bloc est omis.

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
}

Contrôle l’apparence visuelle du diagramme rendu. Le palette mappe les types de nœuds aux couleurs hexadécimales. Le sous-bloc accessibility permet la vérification automatique du contraste WCAG 2.1.

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

Remplacements précis par élément appliqués après le thème. Cascade de règles : by_id remplace by_type. Chaque sous-bloc mappe une clé à une carte de propriétés.

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

Tous les diagnostics incluent un emplacement code, severity, message et un line:col facultatif. Le tableau ci-dessous répertorie tous les codes que la chaîne d'outils peut émettre.

Erreurs (E×××)

• `E100` — L'en-tête magique #!DATRO 1.0 est manquant ou mal formé
• `E201` — ID de nœud en double
• `E202` — Le nœud fait référence à un identifiant de groupe inconnu
• `E301` — Nœud Edge from introuvable
• `E302` — Nœud Edge to introuvable
• `E303` — Le bord weight est négatif
• `E401` — ID de groupe en double
• `E402` — Le groupe members fait référence à un identifiant inconnu
• `E403` — Le nœud est affecté à plusieurs groupes
• `E404` — Imbrication de groupe circulaire détectée
• `E500` — La règle de contrainte comporte une erreur de syntaxe
• `E501` — La règle de contrainte est violée (la gravité reflète celle de la contrainte severity)

Avertissements (W×××)

• `W301` — Bord en double (même de/vers/genre/étiquette)
• `W501` — La règle de contrainte utilise un verbe inconnu
• `W601` — L'étiquette du nœud dépasse max_label_length (80 caractères par défaut)
• `W602` — La couleur de la palette de thèmes est inférieure au contraste WCAG AA (4,5:1)
• `W603` — La couleur de la palette de thèmes est inférieure au contraste WCAG AAA (7.0:1)

Conseils d'information (I×××)

• `I001` — Nœud isolé — aucun bord ne s'y connecte
• `I002` — Groupe vide — aucun membre déclaré
• `I003` — Pas de bloc meta — recommandé pour la documentation
• `I601` — Aucune palette de thème définie — vérifications de contraste ignorées

• Utilisez le CLI Reference pour valider, formater et exporter à partir de la ligne de commande.
• Intégrez des diagrammes dans Markdown avec le Markdown plugin.
• Revenez à Quick Start pour une procédure pas à pas.