Sequence Diagram Markup Language Syntax Reference Guide

If you've ever tried to describe how a system communicates how one service calls another, how a user interacts with a login flow, or how data moves between components you already know that words alone often fall short. Sequence diagrams solve this problem visually, and their markup languages let you create those diagrams from plain text. Having a solid sequence diagram markup language syntax reference at hand means you spend less time guessing syntax and more time documenting what actually matters.

What is a sequence diagram markup language?

A sequence diagram markup language is a text-based syntax that lets you define interactions between components in a structured way. Instead of dragging and dropping boxes in a visual editor, you write short declarations who the participants are, what messages they send, and in what order. A rendering tool then converts that text into a visual sequence diagram.

The most widely used options include PlantUML, Mermaid, and WebSequenceDiagrams. Each has its own syntax rules, but the core concepts overlap: you define participants, describe message exchanges, and optionally add notes, loops, conditions, and alt flows.

Why do developers and architects prefer text-based diagramming?

Text-based sequence diagrams live inside your codebase. That means they're version-controlled, diffable, and reviewable in pull requests. When a colleague changes the interaction flow, you see exactly what changed in the diff no need to compare two image files side by side.

This approach also speeds up drafting. If you can type faster than you can draw, writing Alice -> Bob: Hello takes a fraction of the time it takes to open a diagramming tool, create shapes, draw arrows, and label them. For teams building microservices architecture sequence diagrams, this efficiency adds up quickly across dozens of flows.

What are the core syntax elements you need to know?

Regardless of which markup language you choose, these building blocks appear in almost every sequence diagram:

Participants

Participants are the actors, objects, or systems involved in the interaction. In PlantUML, you declare them with participant. In Mermaid, they're created automatically when you reference them in a message. You can also rename or alias them for cleaner output.

PlantUML: participant "Web Browser" as Browser
Mermaid: Participants are implicit from message declarations, or explicit with participant Browser as "Web Browser"

Messages

Messages show communication between participants. A solid arrow typically means a synchronous call, while a dashed arrow represents a return or response.

Solid arrow: A -> B: Request data
Dashed arrow: B --> A: Return data
Self-call: A -> A: Validate input

Understanding the difference between arrow types is essential. If you want to go deeper on the visual meanings behind each symbol, reviewing sequence diagram notation and symbols will help you avoid misrepresenting your flows.

Activation and deactivation bars

These thin vertical rectangles show when a participant is actively processing something. In PlantUML, you use activate and deactivate. Mermaid handles them with + and - prefixes on participant names.

Notes

Notes let you attach comments or context to specific points in the diagram. PlantUML supports note left of A: description and note right of B: description. Mermaid uses Note over A,B: description to span notes across multiple participants.

Grouping: loops, alternatives, and options

Real-world interactions involve repetition and branching. Both PlantUML and Mermaid support these through grouped blocks:

Loop: loop Every 30 seconds ... end
Alternative (if/else): alt Success ... else Failure ... end
Optional: opt Condition is true ... end
Parallel: par Action A ... and Action B ... end

What does a complete syntax example look like?

Here's a basic PlantUML sequence diagram for a user login flow:

@startuml actor User participant "Frontend App" as FE participant "Auth Service" as Auth participant "Database" as DB User -> FE: Enter credentials FE -> Auth: POST /login activate Auth Auth -> DB: Query user record DB --> Auth: User data Auth --> FE: JWT token deactivate Auth FE --> User: Show dashboard @enduml

The same diagram in Mermaid syntax would look like this:

sequenceDiagram actor User participant FE as Frontend App participant Auth as Auth Service participant DB as Database User->>FE: Enter credentials FE->>Auth: POST /login activate Auth Auth->>DB: Query user record DB-->>Auth: User data Auth-->>FE: JWT token deactivate Auth FE-->>User: Show dashboard

Notice the subtle syntax differences: Mermaid uses >> for arrows while PlantUML uses >. These small distinctions trip up beginners switching between tools.

Which syntax differences between PlantUML and Mermaid matter most?

If your team uses both tools or you're evaluating which one to adopt knowing the key syntax gaps saves real frustration. PlantUML offers richer diagram types, more fine-grained styling, and support for complex grouping. Mermaid has a gentler learning curve and works natively in many Markdown renderers, including GitHub and GitLab.

A detailed comparison of PlantUML vs Mermaid syntax differences can help you pick the right tool before you invest time writing dozens of diagrams.

What common mistakes break sequence diagram markup?

Even experienced developers run into these issues:

Missing closing keywords: Every loop, alt, opt, and par block needs a matching end. Forgetting one produces confusing errors or broken diagrams.
Inconsistent participant names: If you write AuthService in one message and Auth Service in another, the tool creates two separate participants. Use aliases to avoid this.
Wrong arrow syntax: Mixing up solid and dashed arrows misrepresents the flow. Solid means a call; dashed means a return. Using the wrong type changes the diagram's meaning.
Using special characters without escaping: Characters like [, ], <, and > inside message labels can break rendering. Wrap labels in quotes when needed.
Forgetting the start and end tags: PlantUML requires @startuml and @enduml. Without them, the renderer won't process your diagram.

How do you add lifelines, fragments, and advanced features?

Beyond the basics, most markup languages support features that match UML 2.0 specification elements:

Lifelines: Represented automatically by the vertical dashed line beneath each participant. You control them implicitly through activation.
Reference fragments: Use ref over A,B: See login diagram to reference another sequence diagram without duplicating it.
Break: break Error condition ... end shows an interruption that exits the enclosing interaction.
Critical sections: critical Must complete ... end highlights a group of messages that must all succeed.
Delay and spacing: Use ... or ||| to indicate a pause or add vertical space in the diagram.

These features make your diagrams accurate enough for design reviews and technical documentation, not just quick sketches.

Where can you render sequence diagram markup?

You have several options depending on your workflow:

PlantUML Server: A public web service that renders PlantUML text into images via URL encoding.
Mermaid Live Editor: A browser-based editor at mermaid.live where you type Mermaid syntax and see the result instantly.
VS Code extensions: Both PlantUML and Mermaid have extensions that preview diagrams inside your editor.
CI/CD pipelines: Tools like PlantUML can be run as a build step, generating diagram images automatically on every commit.
Markdown platforms: GitHub, GitLab, Notion, and Obsidian support Mermaid code blocks natively no extra setup needed.

What should you do next?

Start by picking one tool PlantUML or Mermaid based on where your team already works. Then try reproducing a real interaction from your system. Start simple: define three participants, describe a request-response cycle, and add one conditional branch. Render it, review it with a teammate, and iterate.

Quick-start checklist: