Language Reference

Referensi sintaksis lengkap untuk file Datro DSL (.dtro). Setiap jenis blok, setiap bidang, setiap kode diagnostik — semuanya di satu tempat.

Setiap file .dtro harus dimulai dengan header ajaib pada baris 1. Parser akan mengembalikan E100 jika hilang atau formatnya salah.

#!DATRO 1.0

Metadata tingkat dokumen opsional. Menghasilkan petunjuk info I003 jika dihilangkan. Semua bidang adalah string/array opsional kecuali 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
}

Mendeklarasikan entitas dalam diagram. Setiap node memiliki id unik, type semantik yang mengontrol bentuk yang dirender dan warna default, dan blok attrs opsional untuk 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" } }

Mendeklarasikan hubungan antara dua node. Arah tepi ditulis langsung dalam deklarasi: -> (terarah), <-> (dua arah), atau -- (tidak terarah).

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

Mengelompokkan node terkait ke dalam kotak subgraf berlabel. Sebuah node dapat tergabung dalam paling banyak satu grup — E403 memicu konflik. Grup dapat disarangkan: id anggota dapat mereferensikan id grup lain.

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
}

Mendeklarasikan aturan arsitektur yang dievaluasi validator terhadap IR. Pelanggaran menghasilkan E501 (atau W501 bila severity: warn). Bidang rule menggunakan tata bahasa tiga token yang ringkas.

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

Kata kerja pembatas

• `!->` — tidak ada node SUBJECT yang memiliki tepi terarah ke node OBJECT mana pun.
• `->` — setiap node SUBJECT harus memiliki setidaknya satu tepi yang diarahkan ke node OBJECT.
• `!<->` — tidak ada tepi dua arah antara node SUBJECT dan OBJECT.
• `<->` — setiap node SUBJECT harus memiliki tepi dua arah ke beberapa node OBJECT.
• `in` — setiap node SUBJECT harus menjadi anggota grup OBJECT.
• `!in` — tidak ada node SUBJECT yang boleh menjadi anggota grup OBJECT.

Membagi diagram besar menjadi beberapa file .dtro. Resolver menggabungkan IR yang diimpor ke induk sebelum validasi. Gunakan as untuk penspasian nama dan expose untuk memasukkan id tertentu ke daftar putih.

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

Petunjuk kepada penyaji tentang cara menyusun grafik. Semua bidang bersifat opsional — penyaji menggunakan default yang masuk akal ketika blok dihilangkan.

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
}

Mengontrol tampilan visual diagram yang dirender. palette memetakan tipe node ke warna hex. Sub-blok accessibility mengaktifkan pemeriksaan kontras WCAG 2.1 otomatis.

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

Penggantian per elemen secara mendetail diterapkan setelah tema. Aturan berjenjang: by_id mengesampingkan by_type. Setiap sub-blok memetakan kunci ke peta properti.

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

Semua diagnostik mencakup lokasi code, severity, message, dan line:col opsional. Tabel di bawah mencantumkan setiap kode yang dapat dikeluarkan oleh rantai alat.

Kesalahan (E×××)

• `E100` — Header ajaib #!DATRO 1.0 hilang atau formatnya salah
• `E201` — ID simpul duplikat
• `E202` — Node mereferensikan id grup yang tidak diketahui
• `E301` — Node tepi from tidak ditemukan
• `E302` — Node tepi to tidak ditemukan
• `E303` — Tepi weight negatif
• `E401` — ID grup duplikat
• `E402` — Grup members mereferensikan id yang tidak diketahui
• `E403` — Node ditugaskan ke lebih dari satu grup
• `E404` — Kumpulan kelompok melingkar terdeteksi
• `E500` — Aturan batasan mengalami kesalahan sintaksis
• `E501` — Aturan batasan dilanggar (keparahan mencerminkan severity batasan itu sendiri)

Peringatan (L×××)

• `W301` — Tepi duplikat (sama dari/ke/jenis/label)
• `W501` — Aturan batasan menggunakan kata kerja yang tidak diketahui
• `W601` — Label simpul melebihi max_label_length (default 80 karakter)
• `W602` — Warna palet tema berada di bawah kontras WCAG AA (4,5:1)
• `W603` — Warna palet tema berada di bawah kontras WCAG AAA (7,0:1)

Petunjuk info (I×××)

• `I001` — Node terisolasi — tidak ada edge yang terhubung dengannya
• `I002` — Grup kosong — tidak ada anggota yang diumumkan
• `I003` — Tidak ada blok meta — direkomendasikan untuk dokumentasi
• `I601` — Tidak ada palet tema yang ditentukan — pemeriksaan kontras dilewati

• Gunakan CLI Reference untuk memvalidasi, memformat, dan mengekspor dari baris perintah.
• Sematkan diagram di Markdown dengan Markdown plugin.
• Kembali ke Quick Start untuk panduan langkah demi langkah.