Docs / Writing diagrams
Syntax reference
Every statement Volley understands, on one page. The pages after this one explain each part in depth.
A Volley diagram is plain text. Each line is one statement, except the lines that belong to a multi-line note or to a payload body. Blank lines are ignored, so use them freely to group related steps. Keywords such as title, note, if and end are not case-sensitive.
Quick reference
| Statement | Form | More |
|---|---|---|
| Title | title: Text | Below |
| Message | From -> To: text | Lanes and arrows |
| Request payload | in: Title on the line after a message, then the body | Requests and responses |
| Response payload | out: Title after a message or its in: block, then the body | Requests and responses |
| Note | note: text, note A: text, note A, C: text, or note: alone for several lines | Notes |
| Branches | if: label ... else: label ... else ... end | Branches |
| Group | group: label ... end | Groups |
| Divider | _: text thin, -: text regular, --: text dashed, =: text bold | Dividers |
| Delay | ...: text or ... | Delays |
| Lane order | order: A, B, C | Ordering lanes |
| Numbering | autonumber | Numbering |
| Comment | // text | Below |
Arrows
| Arrow | Meaning |
|---|---|
A -> B | A request or call, drawn as a solid line with a filled head. |
A --> B | A reply, drawn dashed. A dashed arrow is paired with the request it answers. |
A => B | A bold arrow, for the step that matters most. |
A ->> B | An open head, often used for asynchronous messages and events. |
A -x B | A lost message that never arrives, such as a timeout or a dropped request. |
A <-> B | Both ways, such as a WebSocket or a sync. |
A <- B | Drawn right to left: a message from B to A, written with A first. |
A -> A | A self message, for work a lane does on its own. |
The parts combine. The line can be - (solid), -- (dashed) or = (bold), and each end can have > (filled head), >> (open head) or x (lost). So -->> is a dashed arrow with an open head and <=> is a bold arrow pointing both ways. Write x heads with a space on each side of the arrow.
Title
title: Sign in with a passkeyThe title names the diagram. It is shown in the editor's toolbar, at the top of exported images and embeds, and it becomes the name of the diagram when you save it to your account. Use it once, normally on the first line.
Comments
// The retry policy is described in the runbook
Worker -> Queue: AckA line that starts with // is ignored. Comments are a good place for notes to other authors that readers do not need. In the editor, Ctrl+/ turns comments on and off for the selected lines.
Inside a fenced code block, // is part of the code and not a comment.
Everything at once
This example uses nearly every statement. Open it in the editor and change things to see how the drawing reacts.
title: Place an order
order: Client, Gateway, Orders, Database
autonumber
_: **Create**
Client -> Gateway: POST /orders
in: Body
```json
{ "sku": "BOOK-1", "quantity": 2 }
```
Gateway ->> Orders: Forward with `X-Request-Id`
Orders -> Orders: Validate
Orders -> Database: INSERT order
Database --> Orders: id 1042
Orders --> Gateway: 201 Created
Gateway --> Client: 201 Created
out: Order
```json
{ "id": 1042, "status": "pending" }
```
note: Notes take **Markdown** and icons
-: **Pay**
if: Payment succeeds
Orders => Gateway: order.paid
else: Card declined
Orders -x Gateway: order.failed
end
group: Fulfilment
Orders -> Database: UPDATE status
end
...: A few days later
Client <-> Gateway: WebSocket
Client <- Gateway: push: shipped
Rules worth knowing
- The first colon ends the message head. In
A -> B: text, everything before the first:is lanes and the arrow, and everything after is text. The text can contain more colons and even arrows. - A message needs no text.
A -> Bon its own draws an unlabeled arrow. - Lane names can contain spaces but not commas or colons, and cannot start with
//or contain an arrow. - A payload or multi-line note runs until the next statement. Any line that reads as a statement, such as a message, a note or
end, closes the block. Fence the body if a line inside it would otherwise look like a statement. See Requests and responses. - Sections nest. An
iforgroupcan sit inside another. Keep it to one level so the diagram stays readable. - Errors never blank the diagram. Volley reports each problem with its line and column and keeps drawing everything else. See Troubleshooting.