Spec Writing

Spec Writing

Overview

An engineering spec is a contract. It says WHAT a system, component, endpoint, or message must do — independent of HOW it is implemented.

Three forms dominate modern practice:

• API specs — machine-readable contracts for HTTP (OpenAPI 3.1) and event-driven (AsyncAPI 3.0) interfaces
• Behavior specs — executable narratives (Gherkin / Given-When-Then)
• Data specs — schema contracts (JSON Schema, Avro, Protobuf)

Joel Spolsky’s 2000 series “Painless Functional Specifications” introduced the discipline: a functional spec describes how a product works from the user’s perspective; a technical spec describes internal implementation.

Core Concepts

1. Spec says WHAT, not HOW

A spec that says “internally we’ll use a Redis cache with 5-minute TTL” has leaked implementation.

Litmus test: If you could swap out the implementation entirely and the spec still holds, the spec is at the right level.

2. Contract-first design

Contract-first development: agree on the contract before writing code. The OpenAPI / AsyncAPI document is the source of truth.

3. OpenAPI 3.1 for HTTP APIs

Key top-level fields:

• openapi — version (3.1.0)
• info — name, version, description
• servers — base URLs per environment
• paths — endpoints, verbs, parameters, request/response shapes
• components — reusable schemas, parameters, responses, security schemes

YAML is preferred over JSON for human authoring.

4. AsyncAPI 3.0 for events

Key concepts in v3.0:

• Channels are addressable destinations (Kafka topic, AMQP queue) — decoupled from operations
• Operations describe what an application does on a channel using action: send or action: receive
• Messages are defined once and referenced from channels and operations

5. Gherkin / Given-When-Then for behavior specs

Scenario: Valid percentage discount applies
  Given a discount code "SUMMER10" worth 10%
  When I apply the code at checkout
  Then the cart total is "$45.00"
  And the discount line shows "SUMMER10 (-$5.00)"

Use Gherkin for: business-logic behavior (pricing rules, eligibility checks, state transitions), workflows spanning multiple systems.

Avoid Gherkin for: API shape (use OpenAPI), data format (use JSON Schema).

6. Spec-as-contract mindset

A spec is a promise. Once published:

1. Versioning — non-breaking changes bump minor; breaking changes bump major.
2. Backward compatibility — additive changes (new optional field) are safe; removals, renames, type changes are breaking.
3. Deprecation policy — published timeline (e.g., 12 months notice for major version sunset).

7. Versioning conventions

For HTTP APIs:

• URL versioning (/v1/users) — explicit, cacheable
• Date-pinned versioning (Stripe: Stripe-Version: 2024-04-10) — fine-grained

For events:

• Version in the topic name (orders.v1, orders.v2)
• Schema registry with explicit compatibility modes (BACKWARD, FORWARD, FULL)

8. Examples are part of the spec

OpenAPI’s examples field and Gherkin’s Examples: table are not decorative — they are the spec. CI tools validate that examples conform to the declared schema.

OpenAPI 3.1 minimal endpoint (HTTP)

openapi: 3.1.0
info:
  title: Orders API
  version: 1.4.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order by ID.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Order found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found.

Anti-Patterns

1. Implementation leakage — spec mentions Redis, Postgres, language choice.
2. No examples — schemas without concrete payloads.
3. Hand-waved errors — “returns an error on failure” without listing codes.
4. Missing versioning policy.
5. Spec-test drift — spec says one thing, implementation does another, no CI check.
6. Optional everything — every field is optional, every status code is default.

Decision Heuristics

References

1. Joel Spolsky, “Painless Functional Specifications, Part 2”
2. OpenAPI Specification v3.1: https://spec.openapis.org/oas/v3.1.0
3. AsyncAPI 3.0.0 Specification: https://www.asyncapi.com/docs/reference/specification/v3.0.0
4. Cucumber, “Gherkin Reference”: https://cucumber.io/docs/gherkin/reference/