Sequence diagram
An interaction model where actors sit across the top, time moves downward, and horizontal messages explain a scenario.
Documenting API calls, protocols, authentication, or request/response behavior.
The goal is a static component inventory.
- Time always moves downward.
- Calls are solid and returns dashed.
- Use ALT, OPT, or LOOP frames for branches.
- Limit the default view to five actors and twelve messages.
- Who calls whom?
- In what order?
- What happens on failure?
Notation semantics are separated from Diagram Atlas editorial limits. Every executable rule points to evidence.
What this diagram promises
A sequence diagram explains one interaction scenario. It privileges message order and responsibility—not system inventory or measured duration.
- Who exchanges each message?
- In what order do interactions occur?
- Where do alternatives, optional paths, and repetition change the scenario?
- A static inventory of system components
- Precise elapsed-time or performance measurement
- Ownership lanes in a business process
Five parts, each with one job
The vertical trace of one participant. Occurrence order increases from top to bottom; distance is not literal duration. [1]
A directed communication between lifelines, labeled with an action, request, signal, or result. [1]
A framed region for alternatives, optional behavior, loops, or parallel behavior, with guards in square brackets. [1]
Arrow shape carries meaning
This is the Diagram Atlas visual profile. UML defines message semantics; Mermaid and Diagram Design make the rendering conventions executable.
| Kind | Atlas notation | Meaning | Example |
|---|---|---|---|
| Synchronous call | solid line · filled head | The sender waits while the receiver performs an operation. [3][2] | API → Auth: verify() |
| Reply | dashed line · filled head | A response or returned value from a previous call. [3][2] | Auth ⇢ API: token |
| Asynchronous signal | solid line · open head | The sender emits work without waiting for the receiver to finish. [1][2] | API →) Queue: publish |
| Self-message | loop to same lifeline | A participant calls its own behavior; the loop must remain visibly outside the activation. [3] | Cache ↺ Cache: lookup |
Defaults for a readable first view
These limits are editorial guardrails, not restrictions in UML. Exceeding them produces a warning, not an invalid diagram.
Break the notation. Watch the rules repair it.
This specimen runs the same validator used by the drawing workspace. Introduce three semantic problems, then repair them from the knowledge model.
Every claim has a basis and a check
SEQ-001NormativeRequiredOrder occurrences downward
Read event order from top to bottom on each lifeline. Never use vertical spacing as a promise of elapsed time. [1]
Message order must be explicit; reject reverse-time routing.SEQ-002NormativeRequiredReference declared participants
Every message endpoint must resolve to a participant declared once across the top row. [1]
from and to must match participant IDs.SEQ-003NormativeRequiredFrame conditional behavior
Place alternatives, optional paths, and loops inside a labeled combined fragment; put guards in square brackets. [1]
A conditioned message must reference an alt, opt, or loop fragment.SEQ-004EditorialRecommendedSEQ-005EditorialRecommendedKeep one readable scenario
Start with at most five participants and twelve messages. Treat these as editorial defaults, not UML limits. [3]
Warn above 5 participants or 12 messages.SEQ-006EditorialRecommendedName messages as actions
Use concise verb phrases, operations, or concrete results. Avoid labels such as data, call, or response without context. [3]
Warn on missing or placeholder labels.Common failures and direct repairs
SEQ-003Free-floating branch
Two arrows diverge without a frame or guard.
Fix · Use an alt or opt fragment and label each guard.SEQ-001Timeline by pixel distance
A larger vertical gap is presented as a longer duration.
Fix · Add an explicit timing constraint or use a timing diagram.SEQ-005Message soup
Six or more lifelines and a wall of crossing arrows.
Fix · Extract a sub-scenario and link the two diagrams.SEQ-004Ambiguous arrows
Calls, replies, and fire-and-forget signals all look identical.
Fix · Apply one documented arrow profile consistently.The rules run, not just read
The repository includes a typed validator and automated tests. Issues return stable rule IDs, severity, and the failing data path.
4 participants · 5 messages · endpoints resolve · reply style valid
SEQ-002 · message endpoint is not declared
SEQ-003 · conditioned message has no loop fragment
SEQ-005 · 7 participants and 16 messages exceed the editorial budget
Standards, implementation, editorial judgment
We label the role of each source so an opinion never masquerades as a standard.
- NormativeUnified Modeling Language 2.5.1
Object Management Group · Interaction, lifeline, message, occurrence-order, guard, and combined-fragment semantics.
- ImplementationSequence diagram syntax
Mermaid · Executable syntax for participants, arrows, activations, notes, loops, alternatives, and sequence numbers.
- EditorialSequence diagram design reference
Diagram Design · Cathryn Lavery · Visual defaults, density limits, anti-patterns, and the specimen style. MIT licensed.
id: sequence
version: 1
status: evidence_backed_pilot
intent: ordered_message_exchange
input:
participants: { min: 2, recommended_max: 5 }
messages: { min: 1, recommended_max: 12 }
message_kinds: [sync, reply, async, self]
fragments: [alt, opt, loop]
profile:
sync: { line: solid, arrowhead: filled }
reply: { line: dashed, arrowhead: filled }
async: { line: solid, arrowhead: open }
checks:
- id: SEQ-001
severity: required
basis: normative
- id: SEQ-002
severity: required
basis: normative
- id: SEQ-003
severity: required
basis: normative
- id: SEQ-004
severity: recommended
basis: editorial
- id: SEQ-005
severity: recommended
basis: editorial
- id: SEQ-006
severity: recommended
basis: editorial
provenance:
- omg-uml-251
- mermaid-sequence
- diagram-design-sequence