@draw-my-architecture/diagram-dsl

Cloud-aware diagram DSL parser, validator, and normalizer with Azure-first backward compatibility.

DSL syntax reference (line-based markdown DSL)

This DSL is line-based (one declaration per line), markdown-friendly, and comment-tolerant.

• Use # or // for comments.
• Use key=value options.
• Quote values with spaces: label="My API".
• Escape inside quoted values with \", \\, \n, \r, \t.

diagram <id> [label="..."] [provider=<azure|aws|gcp>] [key=value...]
group <id> [label="..."] [parent=<groupId>] [provider=<azure|aws|gcp>] [groupKind=<group|resourceGroup>] [resourceGroup=<groupId|hint>] [style=<hint>] [key=value...]
node <id> <serviceKey> [label="..."] [group=<groupId>] [provider=<azure|aws|gcp>] [shape=<icon|box>] [resourceGroup=<groupId|hint>] [type=<resourceType>] [style=<hint>] [x=<number>] [y=<number>] [key=value...]
edge <sourceNodeId> -> <targetNodeId> [label="..."] [kind=<dependsOn|connectsTo|dataFlow|contains>] [direction=<oneWay|bidirectional>] [terminator=<default|none|back|both>] [route=<auto|manual>] [bends="x,y;x,y"] [protocol=<name>] [port=<value>] [style=<hint>] [key=value...]
note <id> label="..." [attachTo=<nodeOrGroupId>] [x=<number>] [y=<number>] [width=<number>] [height=<number>]
meta <key>=<value>

Required structure

diagram is required and only one is allowed:

diagram main label="My architecture" provider=azure

Declaration details

1. diagram: top-level identifier, optional label, optional default provider.
2. group: optional containers; supports parent nesting and groupKind=resourceGroup.
3. node: requires <id> <serviceKey>; optional provider/shape/group/resource metadata.
4. edge: must use ->; only node-to-node links are valid.
5. note: floating annotation box; label is required, attachTo draws a dotted amber connector to the target node/group. x/y override position; width/height override box size.
6. meta: free-form metadata as meta key=value.

Validation semantics

• Providers: azure | aws | gcp
• Node shape: icon | box
• Group kind: group | resourceGroup
• Edge direction: oneWay | bidirectional
• Edge terminator: default | none | back | both (controls arrowhead rendering)
• Edge route mode: auto | manual
• Edge bend points:
  • Use bends="x,y;x,y" (semicolon-separated coordinate pairs).
  • Coordinates must be finite numbers in range -100000..100000.
  • bends are only valid for manual routing (route=manual; implied when omitted).
• Edge kind: any string parses; recommended kinds are dependsOn, connectsTo, dataFlow, contains
• Node coordinates:
  • If one of x/y is present, both must be present.
  • Must be finite numbers in range -100000..100000.
• Note annotations:
  • label is required.
  • attachTo must reference an existing node or group id.
  • id must be unique and not conflict with any node or group id.
  • x/y, if provided, must both be present and be finite numbers.
  • width/height, if provided, must be positive numbers.

Defaults (normalization)

• Diagram provider defaults to azure.
• Node shape defaults to icon.
• Group kind defaults to group.
• Edge kind defaults to connectsTo.
• Edge direction defaults to oneWay.
• Edge terminator defaults to default (forward arrow at target).

Example (mixed cloud + resource groups + note)

diagram checkout label="Checkout Platform" provider=azure
group rg-app groupKind=resourceGroup label="App Resource Group"
group apps label="Applications" parent=rg-app
node api appService label="Checkout API" group=apps provider=azure shape=icon resourceGroup=rg-app type=sites x=220 y=120
node ordersDb sqlDatabase label="Orders DB" group=apps provider=azure shape=icon resourceGroup=rg-app
node cdn cloudFront label="Edge CDN" provider=aws shape=icon
edge cdn -> api label="HTTPS" kind=dataFlow direction=oneWay protocol=https port=443
edge api -> ordersDb label="reads/writes" kind=dataFlow
note n1 label="Primary data store\ncopied nightly" attachTo=ordersDb
meta environment=prod

API

import {
  applyNodeLayout,
  compileAzureDsl,
  normalizeAzureDsl,
  parseAzureDsl,
  serializeAzureDsl,
  validateAzureDsl
} from '@draw-my-architecture/diagram-dsl';

const ast = parseAzureDsl(source);
const validation = validateAzureDsl(ast);
const model = validation.isValid ? normalizeAzureDsl(ast) : undefined;
const updated = model ? applyNodeLayout(model, { api: { x: 320, y: 180 } }) : undefined;
const persistedDsl = updated ? serializeAzureDsl(updated) : source;

normalizeAzureDsl emits node fields needed for future icon resolution:

• model.provider (resolved diagram provider, defaults to azure)
• node.provider and node.cloud.provider (azure|aws|gcp)
• node.shape and node.designer.shapeVariant (icon/providerIcon vs box/standardBox)
• group.kind and group.designer.isResourceGroup
• edge.direction plus edge.metadata.routeMode / edge.metadata.bendPoints
• edge.metadata.protocol / edge.metadata.port
• node.azure.serviceKey
• node.azure.resourceType (optional)
• node.azure.iconKey (preserves legacy Azure format)
• node.layout ({ x, y }, optional)

Backward compatibility notes:

• Existing DSL without provider, shape, groupKind, resourceGroup, direction, protocol, or port still parses/normalizes.
• Omitted provider defaults to azure.
• Serializer keeps legacy Azure output compact (no forced provider=azure).

Node layout coordinates are still optional. Add both x=<number> and y=<number> to persist placement:

node api appService x=220 y=120