Cascadia DSL reference

Cascadia renders Mermaid diagrams natively. The Cascadia DSL is an additional layer on top, designed for sequence diagrams and architecture flows, with source mapping between text and picture. For how Mermaid diagram types relate to the DSL, see the Mermaid coverage page.

Quick start

diagram MyDiagram {
  participant User { type: user }
  participant API { type: api }
  participant Database { type: database }

  User -> API: "Request data"
  API -> Database: "Query"
  Database -> API: "Response"
  API -> User: "Return data"
}

Diagrams

Every DSL file defines exactly one diagram.

diagram DiagramName {
  // contents
}

• name — unique identifier and display name.
• Diagrams are automatically timestamped on creation.

Participants

Participants represent actors, services, or systems in the sequence.

participant User { type: user; label: "End User" }
participant API { type: api }
participant Database { type: database; cluster: Platform }

Fields:

• type — actor category: user, browser, mobile, service, api, gateway, database, cache, queue, topic, worker, function, eventbus, external, cluster.
• label — display name (optional; defaults to the ID).
• color — hex color (#RRGGBB; named colors are planned).
• cluster — assign to a cluster boundary (optional).
• icon — override icon (optional; planned).

Shorthand:

participant SimpleParticipant

is equivalent to:

participant SimpleParticipant { type: service }

Clusters

Clusters group participants into visual boundaries — domains, services, or deployment boundaries.

cluster Platform {
  label: "Platform Services"
  contains: API, Database, Cache
  color: #6366F1
}

Fields:

• label — display name.
• contains — comma-separated participant IDs.
• color — boundary color (optional).

Messages

Messages are arrows representing synchronous or asynchronous interactions.

Sender -> Recipient: "Message text"
Sender ..> Recipient: "Async message"
Sender <-- Recipient: "Response"

Arrow types:

• -> — synchronous call (solid line, filled arrowhead).
• ..> — asynchronous message (dashed line, open arrowhead).
• <-- — response / return (dashed line back).

Message text must be a quoted string.

Self-messages (a participant messaging itself) are not currently supported. The planned syntax is:

Service -> Service: "Internal operation"

Fragments

Fragments contain grouped messages with conditional or repetitive semantics. Sections inside a fragment are marked by [condition text] operands; at least one operand is required, and the operand text appears in the diagram label.

alt — alternative (if / then / else)

fragment alt LoginCheck {
  [user has valid token]
  Service -> Database: "Query user"
  Database -> Service: "User data"

  [user no token]
  Service -> OAuth: "Redirect to auth"
  OAuth -> Service: "Token"
}

loop — repetition

fragment loop Retry {
  [up to 3 times]
  Client -> API: "Request"
  API -> Service: "Call external"
}

par — parallel

fragment par FetchAll {
  [fetch users]
  Service -> UserDB: "SELECT *"

  [fetch roles]
  Service -> RoleDB: "SELECT *"

  [fetch permissions]
  Service -> PermDB: "SELECT *"
}

seq — strict order

fragment seq OrderedSteps {
  [step 1]
  A -> B: "First"

  [step 2]
  B -> C: "Second"

  [step 3]
  C -> D: "Third"
}

neg — invalid scenarios

fragment neg InvalidAuth {
  [attacker sends bad creds]
  Attacker -> API: "POST /login { invalid }"
  API -> API: "Reject"
}

Notes

Notes attach text annotations to participants.

note left on User: "This is a note"
note right on Database: "Cached result"
note on User, API: "Both participants"

Positions: left and right (a between position on message lines is planned).

Notes are currently parsed but not yet rendered.

Patterns

Patterns — reusable diagram fragments and libraries — are planned but not yet implemented. The planned syntax:

pattern OAuth2Flow {
  participant User { type: user }
  participant App { type: browser }
  participant AuthServer { type: external; label: "OAuth Provider" }

  User -> App: "Login"
  App -> AuthServer: "Redirect"
  AuthServer -> User: "Grant permission?"
  User -> AuthServer: "Approve"
  AuthServer -> App: "Return token"
  App -> User: "Session established"
}

// Use in another diagram
diagram MyApp {
  participant Client { type: browser }
  participant API { type: api }

  use OAuth2Flow {
    User = Client
    App = API
  }

  Client -> API: "Access resource"
}

Syntax rules

Comments

// Single-line comment

/* Multi-line
   comment */

diagram Test {
  // Comments allowed anywhere
  participant A { type: service }
}

Whitespace

Spaces, tabs, and newlines are flexible. Indentation is optional but recommended.

Identifiers

[a-zA-Z_][a-zA-Z0-9_-]*, case-sensitive. Examples: User, PaymentService, db_primary, cache-layer.

Strings

Double or single quoted:

"Double quoted string"
'Single quoted string'
"String with \"escaped quotes\""

Colors

Hex format:

color: #3B82F6       // RGB
color: #000000       // Black
color: #FFFFFF       // White

Named colors (color: blue) are planned.

Complete example

diagram E-CommerceCheckout {
  // Actors
  participant Customer { type: user; label: "Customer" }
  participant Browser { type: browser }
  participant APIGateway { type: gateway; cluster: Commerce }
  participant CheckoutService { type: service; cluster: Commerce }
  participant PaymentService { type: service; cluster: Commerce }
  participant PaymentProvider { type: external; label: "Payment Provider" }
  participant OrderDB { type: database; cluster: Commerce }

  // Cluster boundary
  cluster Commerce {
    label: "Commerce Services"
    contains: APIGateway, CheckoutService, PaymentService, OrderDB
    color: #6366F1
  }

  // Main flow
  Customer -> Browser: "Add item to cart"

  Customer -> Browser: "Proceed to checkout"
  Browser -> APIGateway: "POST /checkout"

  APIGateway -> CheckoutService: "Create order"
  CheckoutService -> OrderDB: "INSERT order"
  OrderDB -> CheckoutService: "Order ID"

  fragment alt PaymentDecision {
    [credit card available]
    CheckoutService -> PaymentService: "Process payment"
    PaymentService -> PaymentProvider: "Charge card"
    PaymentProvider -> PaymentService: "Success"
    PaymentService -> CheckoutService: "Payment confirmed"

    [wallet selected]
    CheckoutService -> PaymentService: "Use wallet"
    PaymentService -> CheckoutService: "Wallet charged"
  }

  CheckoutService -> OrderDB: "UPDATE order status=paid"
  CheckoutService -> APIGateway: "201 Created"
  APIGateway -> Browser: "{ orderId, status: paid }"
  Browser -> Customer: "Order confirmation page"

  note right on OrderDB: "Order persisted"
  note right on PaymentProvider: "External service"
}

Grammar

diagram         = "diagram" IDENT "{" diag_item* "}"

diag_item       = participant | cluster | message | fragment | note | pattern_def

participant     = "participant" IDENT attr_block?
cluster         = "cluster" IDENT attr_block
message         = IDENT arrow IDENT ":" STRING
arrow           = "->" | "..>" | "<--"

fragment        = "fragment" frag_type IDENT "{" frag_item* "}"
frag_type       = "alt" | "loop" | "par" | "seq" | "neg"
frag_item       = operand | message | fragment
operand         = "[" text "]"

note            = "note" position? "on" participant_ref ":" STRING
position        = "left" | "right"

attr_block      = "{" (attr ";")* "}"
attr            = IDENT ":" value

IDENT           = [a-zA-Z_][a-zA-Z0-9_-]*
STRING          = '"' .*? '"' | "'" .*? "'"

Error messages

Roadmap

Planned, not shipped:

• Notes rendering, canvas edits syncing back to the DSL, participant reordering, and message hover effects.
• Pattern definitions and includes, fragment parameters, a fragment library, and code-to-diagram adapters.
• Named colors, custom icons in stencil packs, formatting, and linting.
• Mermaid import/export, a PlantUML compatibility layer, multi-file imports, and diagram composition.