The .dgm format

A .dgm file describes what exists and how it connects. It can also carry a view, which records the visual decisions you made in Studio. This page lists every keyword in format 1.

Each diagram also needs a sibling <name>.requirements.json file. Extract its component, relationship, count, and placement requirements from the request before authoring .dgm; assign stable IDs in the contract and use the same IDs in the source. Keep the contract beside the diagram during layout changes. dumbdiagrams validate checks completeness against that contract, while --strict also treats routing findings as failures. A passing completeness check does not establish that the written contract understood the original request.

A complete example

dgm 1
diagram payments {
  grammar aws
  flow lr
  title "Payments platform"

  cloud-agnostic.actor customer "Customer"

  aws.region region "AWS Region" {
    aws.api-gateway api "Payments API"
    aws.aws-lambda handler "Payment handler"
    aws.dynamodb ledger "Payment ledger"
  }

  customer -> api { id request step 1 }
  api -> handler { id invoke step 2 }
  handler -> ledger { id persist step 3 }
}

File structure

Strings use double quotes and support the \", \\, \n, \r, and \t escapes. IDs start with a letter or _ and contain letters, digits, _, and -.

Diagram settings

Declarations

A declaration is <catalog-type> <id> "Label". The label is optional. The type decides whether the item is a resource or a boundary. Boundaries contain declarations in braces:

aws.region region "AWS Region" {
  aws.aws-lambda handler "Handler" { role secondary }
}

Boundaries take these options before their children:

Resources take options in braces after the label:

Use cloud-agnostic.boundary for a logical container without provider meaning.

Edges

api -> handler { id invoke label "process" step 2 from e to w }

Annotations

annotation note "Retries use exponential backoff" { anchor handler style callout }

Assets

assets {
  asset logo { svg "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\">…</svg>" w 16 h 16 }
}

Each asset <id> has svg markup and its intrinsic size, w and h. A resource uses it with icon <id>. Assets are sanitized: scripts, event handlers, external references, and non-standard namespaces are rejected.

Views

Studio writes the view for you. Each entry refers to an existing ID:

view default {
  place handler { x 320 y 120 w 96 h 96 pin }
  place cache { visible false }
  route invoke { point 200 160 point 320 160 mode manual pin badge 0.25 top label 0.75 bottom }
  annotation note { x 300 y 80 w 160 h 48 }
}

Errors and warnings

Errors stop the diagram from rendering. They include the line and column:

diagram.dgm:3:8: Invalid flow "sideways"; expected lr, tb

Warnings render but point at something worth fixing. Provider rules are specific to each grammar. For example, managed-service-in-network flags DynamoDB inside a VPC, Key Vault inside a VNet, or BigQuery inside a VPC network, because those managed services sit outside the network. The error generic-cloud-boundary rejects cloud-agnostic.cloud in a provider diagram; use aws.cloud, azure.subscription, or gcp.organization instead. dumbdiagrams validate --strict turns warnings into failures for CI.

Formatting

dumbdiagrams format prints the canonical form: a dgm 1 header, two-space indentation, one declaration per line, and options in a fixed order. Studio saves canonical source too, so diffs stay small. The format has no comments; put notes in an annotation or in the architecture brief beside the file.