liveBook · Manning

Specification format

As explained in Spec-Driven Development

A specification format is a defined structure and notation for recording requirements and decisions with sufficient precision for implementation.

A specification format defines how requirements and decisions are recorded. Its job is to retain enough intent to guide implementation: if a conversation settles validation behavior but the specification records only a vague sentence, the format has lost important distinctions. section 3.2.2 section 3.6.1

Listing 3.2 Capturing malformed URL validation in Gherkin format
Feature: Shorten URL
  Scenario: Reject malformed URL
    Given the user submits a malformed URL
    When the shorten URL request is processed
    Then the service returns the expected validation status
    And the response explains the validation failure
    And no short link is stored

A malformed-URL scenario makes the expected status, explanatory response, and absence of stored data explicit—details a thin requirement could omit. section 3.2.2

Assess a format by the choices it makes and the tradeoffs they create:

  • Requirement structure ranges from natural-language stories and acceptance criteria to constrained formats such as EARS and Gherkin, or machine-parseable formats. More structure can expose missing behavior and reduce interpretation, while machine-parseable syntax takes effort to learn. section 3.6.1
  • Also consider where specifications live, how finely they are divided, and how they are organized. These choices affect verifiability, authorship, review, and the ability to understand the current system. section 3.6.1
  • Strengthen the format when intent was discussed but recorded too loosely. Route other gaps to the workflow stage that allowed them: dialogue, construction constraints, or verification. section 3.2.2 section 3.2.5

How Spec-Driven Development covers it

How deep it goes
Compares natural language, EARS, Gherkin, and machine-parseable structures, and relates format choices to capture fidelity and review.
Examples
Uses a malformed-URL scenario to specify validation status, response messaging, and whether a short link is stored.
What you can do after
Evaluate specification formats by how well they retain intent and by their effects on interpretation, authorship, and review.
How it connects
Connects requirements structure to acceptance criteria, verifiability, authorship, review, and the software development workflow.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spec-Driven Development. The section links point to the parts of the book it draws on.