Plantuml Sequence Diagram Syntax Reference

If you've ever tried to explain how different parts of a system talk to each other maybe a user logging in, an API calling a database, or a payment flow a sequence diagram is one of the clearest ways to do it. And if you want to create those diagrams using plain text instead of dragging boxes around in a tool, PlantUML is the go-to option. But PlantUML's sequence diagram syntax has a lot of moving parts. You need the right keywords, the right arrow styles, and the right grouping logic. This reference walks you through the actual syntax you'll use day to day, with examples you can copy and paste.

What is PlantUML sequence diagram syntax?

PlantUML is an open-source tool that lets you generate UML diagrams from a simple text-based language. The sequence diagram syntax specifically covers how you define participants, messages, conditions, loops, notes, and other interactions that happen over time between objects or actors in your system.

Instead of drawing arrows manually, you write short lines of code that describe who talks to whom and in what order. PlantUML takes that code and renders a clean diagram. The official documentation at plantuml.com covers everything, but it can be overwhelming to parse. This reference focuses on the syntax you'll actually use most often.

How do you declare participants in a sequence diagram?

Participants are the actors, objects, or systems involved in the interaction. You declare them at the top of your diagram, one per line.

participant "Web Browser" as Browser declares a participant with a display name and a short alias
actor "User" as U declares an actor (renders as a stick figure)
database "MySQL" as DB declares a database (renders with a cylinder icon)
queue "RabbitMQ" as MQ declares a queue component
participant "API" as API #LightBlue you can add colors to participants

If you skip the declarations, PlantUML will create participants automatically the first time they appear in a message. But explicit declarations give you control over the display name, order, and styling.

How do you send messages between participants?

Messages are the core of any sequence diagram. PlantUML uses arrows to show the direction and type of each message.

A -> B : Request data solid arrow (synchronous message)
A --> B : Response data dashed arrow (return/response)
A ->> B : Async event open arrowhead (asynchronous)
A -->> B : Async response dashed open arrowhead
A ->x B : Failed request arrow with a cross at the end
A ->o B : Lost? arrow ending with a circle

The arrow style matters because it conveys meaning. A solid arrow usually means the sender waits for a response. A dashed arrow means the response is coming back. An open arrowhead signals a fire-and-forget message.

Syntax example: a basic login flow

@startuml
actor User as U
participant "Web App" as App
database "Auth DB" as DB
U -> App : Enter credentials
App -> DB : Query user
DB --> App : User record
App --> U : Login success
@enduml

You can test this kind of code quickly using an online sequence diagram editor with real-time preview, which saves you from exporting every time you want to check your work.

How do you add conditions and alternative paths?

Real systems don't follow a single straight line. You need alt (alternative), opt (optional), and else blocks to show branching logic.

alt success starts an alternative block with a label
else failure defines the other branch
end closes the current block
opt optional step shows a step that only happens under a condition

Here's what that looks like:

alt valid credentials
App --> U : Login success
else invalid credentials
App --> U : Error message
end

If you need to combine alt and loop blocks together, we wrote a dedicated breakdown of sequence diagram loop and alt fragment code examples that covers nesting patterns.

How do you show loops, parallel actions, and critical sections?

PlantUML supports several fragment types that map directly to UML sequence diagram semantics.

loop 3 times repeats the enclosed messages
loop every 5 minutes loop with a time condition
par shows parallel execution of messages
critical marks a critical section that must succeed
break exits the enclosing loop or alt block early

A simple polling example:

loop until response received
Client -> Server : Poll status
Server --> Client : Still processing
end

How do you add notes, dividers, and grouping?

Notes give context. Dividers separate logical sections. Grouping organizes related messages visually.

note right of App : This validates the token attaches a note to the right of a participant
note left of DB : Temporary lookup attaches a note to the left
note over App, DB : Both check the cache first spans across participants
== Authentication Phase == horizontal divider with a label
group Auth flow wraps messages in a labeled box

How do you show activation bars and lifelines?

Activation bars show when a participant is actively processing. They're optional, but they add clarity when you have nested calls.

activate App starts the activation bar on a participant
deactivate App ends the activation bar
activate DB
destroy DB marks a participant as destroyed (X at the bottom)

You can nest activations when one participant calls another and waits for a response before continuing.

Can you generate sequence diagrams from existing code?

Yes. If you have Java source code, there are tools that analyze method calls and produce PlantUML sequence diagrams automatically. This saves a lot of time for documenting existing systems. We covered the process of generating sequence diagrams from Java source code in a separate article that walks through the setup and configuration.

What are the most common syntax mistakes people make?

Here are the errors that trip people up most often, based on questions in the PlantUML community forums.

Forgetting end for fragments. Every alt, loop, opt, par, group, and critical block needs a matching end.
Using -> when they mean -->. Solid arrows and dashed arrows mean different things. Mixing them up confuses anyone reading the diagram.
Not declaring participants upfront. PlantUML will auto-create them, but the order might not be what you want. Explicit declarations fix this.
Mismatched aliases. If you write participant "App" as Application but later use App -> instead of Application ->, you'll get two separate participants.
Missing the @startuml and @enduml tags. Some renderers need them, some don't. Always include them to be safe.
Overcrowding a single diagram. If your diagram has more than 10–15 messages, consider splitting it into smaller diagrams by phase or use case.

Quick reference: frequently used PlantUML sequence diagram keywords

participant / actor / database / queue declare participants
-> / --> / ->> / -->> message arrows
activate / deactivate activation bars
alt / else / end conditional branching
opt optional block
loop repetition
par parallel execution
critical / break critical sections
group visual grouping
note annotations
== section dividers
ref over reference to another diagram
return shorthand for a return message
title diagram title
footer / header page header/footer text
skinparam global styling options
autonumber auto-number all messages

Next steps checklist

Pick one flow from your project a login, a checkout, or an API call and write it out in PlantUML syntax.
Use an online editor with live preview to iterate quickly.
Add one fragment (alt or loop) to cover the error path or retry logic.
Share the diagram with a teammate and see if they understand the flow without your explanation. If they do, the diagram works.
Once comfortable, explore auto-generating diagrams from your existing Java source code to document systems you haven't diagrammed yet.