Specify Service Protocol Paths with UML 2.x Combined Fragments

Problem and useful takeaway

A service protocol is often described in prose or hidden inside class diagrams. That leaves implementation and test teams uncertain about what happens when a condition is false, a message must repeat, or a timeout occurs.

Use UML 2.x sequence diagrams with combined fragments to specify one interaction at a time. A combined fragment groups messages under an interaction operator such as alt, opt, loop, or break. Each branch inside the fragment, called an operand, carries a guard, which is a Boolean predicate that decides whether that path executes. A lifeline is the vertical line that represents a participant across time. This makes normal, conditional, optional, repeated, and exceptional paths explicit before anyone writes code.

Desired outcome

A single sequence diagram for one service interaction where every branch has a guard, every message has a sender and receiver, and the no-match or default behavior is stated explicitly.

Prerequisites

• A modeling tool that supports UML 2.x sequence diagrams and combined fragments. Tool support and export fidelity vary, so confirm fragment rendering before relying on the output.
• One lifeline per participating object or actor.
• The message order for the successful, or happy, path.
• Testable predicates for business conditions. Avoid vague terms such as usually or when appropriate unless the implementation can evaluate an explicit condition.

Procedure

1. Draw the happy path

Place lifelines horizontally and draw messages vertically in chronological order. Start with the successful exchange only, without branches.

2. Add conditional branches with alt

Wrap mutually exclusive outcomes in an alt fragment. Each operand inside alt needs a guard. For example, one branch handles a valid cancellation and another handles an already-shipped order. Do not let guards overlap unintentionally.

3. Add optional behavior with opt

Use an opt fragment for a path that may or may not run, such as sending a confirmation email only when the customer requested it. The opt fragment contains a single operand with a guard.

4. Mark repetition with loop

Use a loop fragment when a message or group of messages repeats. Include a guard such as retryCount < 3 and an exit condition so the loop cannot run forever.

5. Add early exit with break

Use a break fragment for exceptional exits such as a gateway timeout or user cancellation. Messages inside a break typically abandon the rest of the interaction.

Concrete example: order cancellation protocol

The following illustrative model source shows an order cancellation interaction. Verify the syntax against your modeling tool before using it.

@startuml
actor Customer
boundary "Order Service" as OS
database "Order Repository" as OR

Customer -> OS: cancelOrder(orderId)
alt [order is cancellable]
  OS -> OR: loadOrder(orderId)
  opt [customer requested email]
    OS -> Customer: sendCancellationConfirmation()
  end
  loop [retryCount < 3]
    OS -> OR: revalidateInventory(orderId)
  end
  OS -> Customer: cancellationAccepted()
else [order already shipped]
  OS -> Customer: cancellationRejected(alreadyShipped)
end
break [gateway timeout]
  OS -> Customer: serviceUnavailable()
end
@enduml

Run this in a PlantUML-compatible editor or server. Required permissions are limited to reading the source file and writing the rendered image. Expected check: verify that the rendered image contains four lifelines, the alt fragment with two guarded operands, and the opt, loop, and break fragments. Risk: some tools render fragment labels differently or drop guards during export, so inspect the exported image in the target tool.

Expected checks

• Every branch inside alt, opt, loop, and break has a guard written as a predicate, not prose.
• Alternative guards do not overlap unless overlap is intentional.
• Fallback or no-match behavior is explicit, for example an else operand in alt.
• Each message names a plausible sender, receiver, and position in the sequence.
• The diagram renders correctly in the target modeling tool and in its exported image or model file.

Limitations

Sequence diagrams show interactions, not complete object state or deployment topology. Use class, state, or component diagrams for those concerns. An omitted branch does not mean the behavior is impossible; state the default explicitly. UML 2.x is a suitable baseline, but notation support varies by tool.

Practical verification

1. Ask a domain reviewer to trace each guard to a requirement and a test case, including the case where no alternative matches.
2. Walk through the main path, one alternative, the loop, and the break path with implementers and testers, checking message order.
3. Inspect the diagram in the target modeling tool and its exported image to confirm fragments, guards, and lifelines render as intended.
4. Compare the final diagram with the implemented interface contract and update the model when behavior changes.

Recovery options

• If the diagram becomes crowded, split it into smaller interactions, one diagram per protocol scenario.
• If guards describe lifecycle rules rather than message conditions, move those rules to a state-machine diagram.
• If guards are ambiguous, rewrite them as testable conditions before coding.

No rollback is required because creating a model does not change runtime state. Version-control the model file and treat earlier revisions as the rollback point.