SpecDDHow to use the Returns section
This guide shows you how to use the Returns section in a SpecDD .sdd file.
Returns lists return values, output types, response shapes, result states, generated artifacts, output files, exit
values, or other observable results.
Short answer
Use Returns for what the subject produces when it succeeds or completes. Keep failure conditions in Raises, inputs
in Accepts, and side-effect or handling behavior in Must or Handles when needed.
Syntax
Returns:
updated itinerary
validation message when an itinerary item cannot be addedRules:
Returnsis a mixed-entry body section.- It may contain text, symbols, paths, key-value lines, or prose.
- It must not have inline text after
Returns:. - Body entries use two spaces.
Steps
1. List outputs people can observe
Examples:
Returns:
updated itinerary
ItineraryUpdateResultFor a CLI:
Returns:
exit code 0 when checks pass
generated report fileFor an API:
Returns:
200 response with updated itinerary
400 response for validation failureIf your project treats error responses as raised failure states, put those in Raises instead.
2. Use result states when values vary
Returns:
saved state when the itinerary item is valid
unchanged state when validation failsThis helps tests and review focus on observable behavior.
3. Separate failure behavior
Returns:
updated itinerary
Raises:
ItineraryPlaceRequired
ItinerarySaveFailedThis keeps success outputs and failure conditions easy to scan.
4. Pair with Accepts
Together:
Accepts:
place name
trip date
Returns:
updated itineraryThe pair describes a small interface contract.
Common mistakes
- Listing input fields in
Returns. - Hiding error conditions in a success output line.
- Describing implementation internals rather than observable output.
- Leaving generated files or exit codes unspecified for automation specs.
- Updating code output without updating
Returns.
How to verify the result
The Returns section is useful when:
- outputs are observable
- success and failure are separated clearly
- tests or scenarios can check important outputs
- generated artifacts and exit codes are included when relevant
- output changes are visible in review