Language Reference

Referencia de sintaxis completa para Datro DSL (archivos .dtro. Cada tipo de bloque, cada campo, cada código de diagnóstico, todo en un solo lugar.

Cada archivo .dtro debe comenzar con el encabezado mágico en la línea 1. El analizador devuelve E100 si falta o tiene un formato incorrecto.

#!DATRO 1.0

Metadatos opcionales a nivel de documento. Produce I003 sugerencia de información si se omite. Todos los campos son cadenas/matrices opcionales excepto 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
}

Declara una entidad en el diagrama. Cada nodo tiene una identificación única, un type semántico que controla su forma representada y su color predeterminado, y un bloque attrs opcional para metadatos.

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

Declara una relación entre dos nodos. La dirección del borde se escribe directamente en la declaración: -> (dirigida), <-> (bidireccional) o -- (no dirigida).

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

Agrupa nodos relacionados en un cuadro de subgrafo etiquetado. Un nodo puede pertenecer como máximo a un grupo: E403 activa los conflictos. Los grupos se pueden anidar: una identificación de miembro puede hacer referencia a otra identificación de grupo.

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
}

Declara una regla arquitectónica que el validador evalúa con respecto al IR. Las violaciones producen E501 (o W501 cuando severity: warn). El campo rule utiliza una gramática concisa de tres tokens.

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

Verbos de restricción

• `!->` — ningún nodo SUBJECT puede tener un borde dirigido a cualquier nodo OBJECT.
• `->`: cada nodo SUBJECT debe tener al menos un borde dirigido a un nodo OBJECT.
• `!<->`: no puede existir ningún borde bidireccional entre los nodos SUBJECT y OBJECT.
• `<->`: cada nodo SUBJECT debe tener un borde bidireccional hacia algún nodo OBJECT.
• `in`: cada nodo SUBJECT debe ser miembro del grupo OBJECT.
• `!in` — ningún nodo SUBJECT puede ser miembro del grupo OBJECT.

Divide diagramas grandes en múltiples archivos .dtro. El solucionador fusiona el IR importado con el principal antes de la validación. Utilice as para el espacio de nombres y expose para incluir en la lista blanca identificadores específicos.

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

Consejos para el renderizador sobre cómo organizar el gráfico. Todos los campos son opcionales: el renderizador utiliza valores predeterminados sensatos cuando se omite el bloque.

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
}

Controla la apariencia visual del diagrama renderizado. El palette asigna tipos de nodos a colores hexadecimales. El subbloque accessibility permite la comprobación automática del 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
  }
}

Anulaciones detalladas por elemento aplicadas después del tema. Cascada de reglas: by_id anula by_type. Cada subbloque asigna una clave a un mapa de propiedades.

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

Todos los diagnósticos incluyen una ubicación code, severity, message y una ubicación opcional line:col. La siguiente tabla enumera todos los códigos que la cadena de herramientas puede emitir.

Errores (E×××)

• `E100` — Falta el encabezado mágico #!DATRO 1.0 o está mal formado
• `E201` — ID de nodo duplicado
• `E202` — El nodo hace referencia a una identificación de grupo desconocida
• `E301` — Nodo de borde from no encontrado
• `E302` — Nodo de borde to no encontrado
• `E303` — El borde weight es negativo
• `E401` — ID de grupo duplicado
• `E402` — El grupo members hace referencia a una identificación desconocida
• `E403` — El nodo está asignado a más de un grupo
• `E404` — Se detectó anidamiento de grupo circular
• `E500` — La regla de restricción tiene un error de sintaxis
• `E501` — Se infringe la regla de restricción (la gravedad refleja la propia severity de la restricción)

Advertencias (W×××)

• `W301` — Borde duplicado (mismo desde/hasta/tipo/etiqueta)
• `W501` — La regla de restricción utiliza un verbo desconocido
• `W601` — La etiqueta del nodo excede max_label_length (80 caracteres predeterminados)
• `W602` — El color de la paleta del tema cae por debajo del contraste WCAG AA (4.5:1)
• `W603` — El color de la paleta del tema cae por debajo del contraste WCAG AAA (7.0:1)

Consejos informativos (I×××)

• `I001` — Nodo aislado — no hay bordes conectados a él
• `I002` — Grupo vacío — no hay miembros declarados
• `I003` — Sin bloque meta — recomendado para documentación
• `I601` — No hay paleta de temas definida — se omitieron las comprobaciones de contraste

• Utilice CLI Reference para validar, formatear y exportar desde la línea de comando.
• Incruste diagramas en Markdown con Markdown plugin.
• Vuelva a Quick Start para ver un tutorial paso a paso.