Language Reference

Full syntaxreferanse for Datro DSL-filer (.dtro-Filer). Hver blokktype, hvert felt, hver diagnosekode alt på ett sted.

Alle .dtro-Fil må starte med Magic-header i linje 1. Parseren gir E100 Retur hvis den mangler eller er feilaktig.

#!DATRO 1.0

Valgfrie metadata på dokumentnivå. Gir informasjonsmeldingen I003 dersom blokken utelates. Alle felt unntatt kind er valgfrie strenger eller matriser.

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

Deklarerer en enhet i diagrammet. Hver knute har en unik ID, en semantisk type, som styrer sin omformede form og standardfarge, og en valgfri 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" } }

Deklarerer et forhold mellom to knopper. Den kantlige retningen blir skrevet direkte i deklarasjonen: -> (rettet), <-> (bidirectional) eller -- (Uregistert).

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

Grupper relaterte knopper i et overskrevet underdiagramfelt. En knute må ikke tilhøre en gruppe – E403 blir utløst i konflikter. Gruppen kan være pakket: En medlem-ID kan henvise til en annen gruppe-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
}

Utser en arkitektonisk regel som validatoren vurderer på basis av IR. Generere overtredelser E501 (eller W501, når severity: warn). Feltet rule bruker en fast tre-token grammatikk.

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

Begrensningsregler

• `!->` – Ingen SUBJECT-knot må ha en rett kant mot noen OBJECT-knot.
• `->` – Hver SUBJECT-knot skal ha minst en rett kant til en OBJECT-knot.
• `!<->` – mellom knopene SUBJECT og OBJECT må det ikke være en bi-direktionskant.
• `<->` – Hver SUBJECT-knot skal ha en bidirectionell kant til en OBJECT-knot.
• `i` hver SUBJECT-knot må være medlem av gruppen OBJECT.
• `!In` ingen SUBJECT-knot kan være medlem av gruppen OBJECT.

Spliter store diagrammer i flere .dtro-Filer opp. Resolveren kombinerer den importerte IR før validering med den overordnede IR. Bruk as for navneområdet, og expose, for å sette bestemte ID-er på den hvite listen.

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

Informasjon til returneren om hvordan diagrammet skal arrangeres. Alle feltene er valgfrie returneren bruker fornuftige standardverdier når blokken blir slettet.

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
}

Styr den visuelle utseendet på det returnerte diagrammet. Den palette Ordner knotttyper med hex farger. Underblokken accessibility muliggjør automatisk WCAG 2.1 kontrastkontroll.

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

Fint graderte overskrifter per element som brukes etter temaet. Regelkaskade: by_id overskrev by_type. Hver underblokke ordner en nøkkel til en egenskap til.

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 diagnoser omfatter en code, severity, message og en valgfri line:col-Sted. I tabellen nedenfor er alle koder som verktøykjeden kan utgi.

Fejl (E)×××)

• `E100` Magic-header #!DATRO 1.0 mangler eller er feilaktig
• `E201` Dopplet knop-ID
• `E202` Knot refererer til en ukjent gruppe-ID
• `E301` Edge-knot from ikke funnet
• `E302` Edge-knot to ikke funnet
• `E303` Kante vekt er negativ
• `E401` Dobbel gruppe-ID
• `E402` gruppe members refererer til en ukjent ID
• `E403` Knotter er tildelt mer enn en gruppe
• `E404` Kastet av sirkulære grupper oppdaget
• `E500` Begrensningsregelen viser en syntaxfeil
• `E501` begrensningsregelen blir brutt (sværhetsgrad reflekterer egen severity av begrensningen))

Varminger (B)×××)

• `W301` Klipper kant (lik til/til/art/skilt))
• `W501` Begrensningsregelen bruker et ukjent verb
• `W601` Knotnavnet overstiger max_label_length (standard 80 tegn))
• `W602` Fargen på temapaletten er under WCAG AA-kontrast (4,5:1)
• `W603` Fargen på temapaletten er under WCAG AAA-kontrast (7,0:1)

Informasjonsinformasjon (I)×××)

• `I001` Isolasjonerte knopper ingen kanter er knyttet til den
• `I002` Emne gruppe ingen medlemmer
• `I003` Ingen meta-block anbefalt for dokumentasjon
• `I601` Ingen tema-palette definert Overskutt kontrastundersøkelser

• Bruk CLI Reference for å validere, formatere og eksportere via kommandoene.
• Legg inn diagrammer i markdown med markdown plugin.
• Gå tilbake til quick start for en steg-for-steg-håndledning.