Plantuml Sequence Diagram Syntax Reference

If you work with software documentation, architecture planning, or team communication, you have probably needed to describe how components interact with each other over time. PlantUML sequence diagrams let you do exactly that using plain text instead of dragging boxes around in a drawing tool. Having a solid PlantUML sequence diagram syntax reference handy saves you from constantly searching for the right keywords, arrow types, and formatting options every time you sit down to document a process.

What Is a PlantUML Sequence Diagram?

A PlantUML sequence diagram is a text-based diagram that shows how different participants (objects, systems, users, or services) exchange messages in a time-ordered flow. You write simple markup, and PlantUML renders a visual diagram from it. This approach falls under the broader category of diagram-as-code tools for developers, where diagrams live alongside your source code and get version-controlled just like any other file.

Because you define everything in text, you can diff changes, review diagram updates in pull requests, and generate diagrams automatically in your build pipeline. No binary image files to manage. No proprietary file formats that lock you into one editor.

How Do You Start a Sequence Diagram in PlantUML?

Every sequence diagram begins and ends with specific keywords. Here is the bare minimum you need:

@startuml
Alice -> Bob: Hello there
@enduml

The @startuml and @enduml tags wrap your diagram definition. Between those tags, each line represents a message or a structural element. PlantUML automatically creates participant boxes from the names you use in message lines.

How Do You Declare Participants?

You can let PlantUML auto-detect participants from your message lines, but explicit declarations give you more control over ordering, aliases, and display names.

actor "User" as U declares a stick-figure actor with an alias
participant "Order Service" as OS standard participant box
database "PostgreSQL" as DB database-shaped box
queue "RabbitMQ" as MQ queue-shaped box
collections "Cache Layer" as CL collections-shaped box

The declaration order determines the left-to-right positioning of participants in the rendered diagram. If you want to reorder them, change the declaration order rather than relying on automatic detection.

What Arrow Types Are Available?

Arrow syntax is the core of any sequence diagram. PlantUML supports several arrow styles that communicate different types of interaction:

A -> B solid arrow with a solid head (synchronous message)
A ->> B solid arrow with an open head (asynchronous message)
A --> B dashed arrow (return or response message)
A -->> B dashed arrow with an open head
A ->o B arrow ending with a circle
A o-> B arrow starting with a circle
A <-> B bidirectional solid arrow
A <--> B bidirectional dashed arrow

You can also add x at the end (like A ->x B) to indicate a lost message, or use o to show a found message. These small details make your diagrams more precise and closer to formal UML semantics.

How Do You Add Notes and Comments?

Notes give context to specific messages or participants. PlantUML offers several placement options:

note left of Alice: She initiated the request
note right of Bob: He processes it
note over Alice, Bob: This is a shared note

For multi-line notes, use the end note syntax:

note left of Alice
This note spans
multiple lines
end note

Floating notes (not attached to any participant) can be positioned using rnote or by placing them after a specific message number.

How Do You Show Loops, Alternatives, and Conditions?

Sequence diagrams in PlantUML support combined fragments that mirror UML's interaction operators. These are some of the most commonly used ones:

Loops:

loop every 5 minutes
Alice -> Bob: Heartbeat ping
Bob --> Alice: Ack
end

Alternative (if/else):

alt success
Bob --> Alice: OK response
else failure
Bob --> Alice: Error response
end

Optional:

opt authenticated request
Alice -> Bob: Protected resource
end

Parallel:

par send email
Alice -> EmailService: Welcome email
also send notification
Alice -> PushService: Push notification
end

You can nest these blocks inside each other, which is useful for modeling complex workflows with multiple decision points.

How Do You Group Messages Into Boxes and Dividers?

When your diagram covers a long flow, visual grouping helps readers follow the logic.

box "Authentication Phase" #LightBlue ... end box wraps participants and messages in a colored region
== Step 3: Payment Processing == inserts a horizontal divider with a label

Dividers work well for breaking a long sequence into logical stages without adding structural complexity.

How Do You Show Object Creation and Destruction?

Sequence diagrams sometimes need to show when a participant appears or disappears during the interaction:

create Participant C the participant is created at this point in the sequence
destroy C the participant is destroyed (shown with an X marker)

Creation messages use a dashed arrow with a create keyword:

Alice -> create C: new C()

How Do You Use Activation and Deactivation?

Activation bars (the thin rectangles on lifelines) show when a participant is actively processing. You can control these manually:

activate Bob starts an activation bar on Bob's lifeline
deactivate Bob ends it

You can also use shorthand by adding + and - to your arrows:

Alice -> Bob: Process order
activate Bob
Bob -> DB: Query inventory
DB --> Bob: Results
deactivate Bob
Bob --> Alice: Order confirmed

PlantUML often auto-generates activation bars, but explicit control keeps your diagram accurate when multiple calls overlap.

How Do You Handle Self-Messages and Ref Frames?

A participant can send a message to itself:

Alice -> Alice: Validate input

This shows a message arrow that loops back to the same lifeline. Self-activation is automatically drawn if you use activate and deactivate around it.

For referencing another sequence diagram (a "ref" frame), you can use:

ref over Alice, DB: See Authentication Sequence

This is useful when you want to point readers to a more detailed sub-diagram without cluttering the current one.

How Do You Customize the Look of Your Diagram?

PlantUML supports skin parameters that change the visual style:

skinparam backgroundColor #FEFEFE
skinparam sequenceArrowThickness 2
skinparam roundcorner 10
skinparam maxMessageSize 200
hide footbox removes the foot boxes at the bottom of lifelines

You can also apply inline styling with #color on individual elements and use themes by including predefined style sheets.

What Are Common Mistakes When Writing Sequence Diagrams?

These errors come up frequently, especially when you are new to PlantUML syntax:

Missing @enduml the renderer will throw a syntax error, and the cause is not always obvious
Mismatched alt/else/end blocks every alt, loop, opt, and par block must have a matching end
Confusing arrow direction -> sends rightward, <- sends leftward, and mixing them up reverses the message flow
Forgetting return arrows using --> for responses clarifies that a message is a return value, not a new request
Overcrowding a single diagram splitting complex flows across multiple linked diagrams with ref frames keeps things readable
Not using aliases long participant names repeat in every message line; aliases reduce clutter and make edits easier

What Are Useful PlantUML Sequence Diagram Shortcuts?

A few lesser-known features can speed up your workflow:

autonumber automatically numbers every message, which helps during reviews and discussions
autonumber 10 10 starts at 10 and increments by 10
header My Diagram Title adds a header to the rendered output
footer Page 1 adds a footer
title Diagram Title adds a centered title above the diagram
newpage splits the diagram across multiple pages in the output
group Authentication similar to box but labeled with a UML combined fragment frame

These features are especially helpful when you are generating documentation from PlantUML files automatically.

How Does PlantUML Compare to Other Diagram Tools?

PlantUML is not the only text-based diagram option available. If you are evaluating alternatives, tools like Mermaid for flowcharts and other Mermaid diagram examples are worth exploring. Mermaid has a simpler syntax and integrates natively with GitHub Markdown, while PlantUML supports a wider range of diagram types and more detailed UML constructs. Your choice depends on whether you need basic flow documentation or formal UML modeling.

For the official syntax details and full feature list, the PlantUML sequence diagram documentation is the authoritative reference maintained by the project.

Quick Syntax Checklist for Your Next Diagram

Wrap everything in @startuml and @enduml
Declare participants in the order you want them displayed
Use -> for requests and --> for responses
Add autonumber for easier discussion references
Use alt/else/end for conditional flows
Use loop/end for repeated interactions
Add notes for context that the arrows alone cannot convey
Break long diagrams with ref frames or == dividers
Use aliases for long participant names
Test your diagram by rendering it at each major edit do not batch a full document and troubleshoot at the end

Start by sketching the simplest version of your flow with just participants and messages. Once the basic shape looks right, layer on notes, fragments, and styling. That incremental approach catches syntax errors early and keeps your diagrams clear from the start.