Plantuml Sequence Diagram Script Reference Manual

If you've ever stared at a blank text editor trying to map out how two systems talk to each other, you know the frustration of getting sequence diagrams right. PlantUML lets you write those diagrams as plain text scripts no drag-and-drop, no bloated software. But the syntax has quirks, edge cases, and options that aren't always obvious. That's where a solid reference manual for PlantUML sequence diagram scripts becomes your best friend. Whether you're documenting an API flow or debugging a race condition between services, having the full syntax at your fingertips saves hours of trial and error.

What is a PlantUML sequence diagram script?

A PlantUML sequence diagram script is a plain-text file written in PlantUML's domain-specific language that describes interactions between participants over time. You define who the actors are (using the participant keyword), then describe messages they send to each other with arrows. PlantUML compiles this text into a visual diagram usually a PNG or SVG image.

Here's the simplest possible example:

@startuml Alice -> Bob: Hello Bob --> Alice: Hi there @enduml

That's it. Two lines of actual diagram logic, and you get a clean sequence diagram showing a request and response. The @startuml and @enduml tags wrap every diagram.

For developers who want a deeper dive into scripting patterns, our sequence diagram scripting guide for system architects covers workflow-level design decisions that pair well with the syntax reference here.

Why do people search for a PlantUML reference manual instead of just using examples?

Examples get you started. But real-world diagrams need features that basic tutorials skip activation bars, grouping messages, notes attached to specific lifelines, loop constructs, alternative paths, and color/style customization. A reference manual gives you the complete picture.

Common reasons developers look for a reference:

They need a specific keyword and can't remember if it's alt, else, or opt
They want to add styling but don't know the skinparam options available
They're converting a whiteboard sketch into a reproducible script
They need to handle advanced scenarios like self-calls, nested fragments, or destroy messages
Their team is adopting PlantUML and needs a shared reference document

How do you define participants and give them custom names?

By default, PlantUML creates participants in the order they appear in messages. But you'll often want control over naming, ordering, and appearance.

Basic participant declaration:

participant "Web Browser" as WB participant "API Gateway" as AG participant "Database" as DB

The as keyword lets you give a short alias so you don't have to type the full name in every message line. You can also use actor, boundary, control, entity, and collections to change the icon shape of a participant.

actor User boundary "Login Page" as LP control "Auth Service" as AS entity "User DB" as UDB

Each of these renders with a different visual style actors get stick-figure icons, boundaries get rounded rectangles with a line on the left, and so on.

What arrow types are available and when should you use each one?

Arrow style communicates meaning. A synchronous call looks different from an asynchronous message or a return. Here's the quick breakdown:

-> Solid arrow (synchronous call)
--> Dashed arrow (return/response)
->> Solid open arrow (asynchronous)
-->> Dashed open arrow (asynchronous return)
-x Solid arrow ending with an x (lost message)
o-> Arrow starting with a circle (found message)

You can also add color to arrows:

Alice -[#red]> Bob: urgent request

Choosing the right arrow isn't just cosmetic it helps anyone reading the diagram understand whether a call blocks, whether a response is expected, and whether messages can be lost. If you're building these scripts in a team setting, the sequence diagram script syntax guide for developers covers conventions for keeping diagrams readable across large codebases.

How do you show loops, alternatives, and parallel execution?

PlantUML uses fragments (also called combined fragments in UML spec) to represent control flow. These are the constructs you'll use most:

Loop

loop Every 30 seconds Client -> Server: Heartbeat Server --> Client: ACK end

Alternative (if/else)

alt Success Server --> Client: 200 OK else Failure Server --> Client: 500 Error end

Optional

opt User is admin Client -> AdminPanel: Show controls end

Parallel

par Send email Service -> EmailService: Notify else Send SMS Service -> SMSService: Notify end

You can also nest fragments inside each other. A loop containing an alt block is perfectly valid and commonly seen in real-world authentication or retry logic diagrams.

How do you add notes, boxes, and dividers to organize your diagram?

When diagrams get complex, visual organization matters. PlantUML offers several layout helpers:

Notes:

note right of Alice: She initiates the request note left of Bob: Handles the business logic

Boxes (group participants):

box "Internal Services" #LightBlue participant AuthService participant PaymentService end box

Dividers (separate phases):

== Authentication Phase == == Data Processing Phase ==

These don't change the logic of your diagram but dramatically improve readability. A 40-line script with no dividers or notes is much harder to review than one with clear sections.

What are common mistakes when writing PlantUML sequence diagram scripts?

After working with PlantUML across dozens of projects, these are the errors that come up most:

Missing @startuml/@enduml tags. Every diagram needs these. Without them, the renderer won't know where your diagram starts or ends.
Forgetting to declare participants with aliases. If two participants share similar names or if you rely on auto-ordering, your diagram layout can shift unexpectedly when you add new messages.
Not closing fragments. Every loop, alt, opt, or par block needs a matching end. One missing end and the entire diagram breaks.
Overusing colors and styles. A little color helps. Too much makes the diagram look like a cluttered dashboard. Stick to one or two accent colors at most.
Writing one massive diagram. If your sequence has more than 30 messages, consider splitting it into smaller, focused diagrams. Use ref to reference sub-diagrams.

How do you handle activation bars and lifeline control?

Activation bars show when a participant is actively processing a request. They're the thin rectangles running along a participant's lifeline.

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

You can nest activations if Bob calls DB while handling Alice's request, DB's activation bar appears inside Bob's. This mirrors real execution stacks and helps readers understand blocking behavior.

Can you reference other diagrams or create multi-diagram documentation?

Yes. PlantUML supports a ref frame that shows a reference to another diagram within your sequence. This is useful for splitting complex workflows into digestible pieces:

ref over Client, Server: See authentication flow

This renders as a labeled box spanning the referenced participants, pointing readers to a separate diagram. For teams building architectural documentation, combining multiple referenced diagrams into a navigation structure is a practical approach. Our guide for system architects covers how to structure multi-diagram documentation effectively.

What styling and skinparam options matter most?

The skinparam command controls visual properties globally. The options you'll actually use regularly:

skinparam sequenceArrowThickness 2 makes arrows more visible
skinparam responseMessageBelowArrow true puts return labels below the arrow
skinparam sequenceParticipantBorderColor #333 custom border color
skinparam sequenceLifeLineBorderColor #999 lifeline color
skinparam sequenceGroupBorderColor #0066CC fragment box border
skinparam shadowing false removes drop shadows for a cleaner look

You can also apply styles to individual elements using the header, footer, and title commands to add context to your exported diagrams.

Where should you go from here?

If you have the syntax basics down and want to focus on script structure and conventions across a team, the script syntax guide for developers covers patterns and naming conventions that keep diagrams maintainable over time.

For the official specification and the most up-to-date keyword list, the PlantUML official sequence diagram documentation is the authoritative source.

Quick reference checklist

Wrap every diagram in @startuml / @enduml
Declare participants with aliases for stable layout
Use the right arrow type for synchronous, asynchronous, and return messages
Close every fragment with end
Add notes and dividers once diagrams exceed 15 messages
Use activation bars to show processing depth
Split large flows with ref instead of cramming everything into one diagram
Set skinparam defaults at the top of your script for consistent styling
Keep color usage minimal one or two accent colors max
Test your script in the PlantUML online server before committing to documentation