From PRD to OpenAPI: A Continuous Pipeline to Keep Specs, Tests, and Feature Cards in Sync

Treat the PRD as the canonical intent document, but written to be translatable. That means each feature entry should include: goal, user journey, explicit acceptance criteria, expected API surface (endpoints + important fields), and non-functional constraints (rate limits, auth). If a PRD lacks this structure, converting it will produce tests that check the wrong things.

For practical hygiene, keep each feature in its own folder (e.g., features/checkout/README.prd.md) and link a short machine‑readable metadata block at the top. That header will be the input for the generator that emits an OpenAPI stub, acceptance tests, and a JSON‑LD feature card.

Convert the structured PRD header into an OpenAPI skeleton using a small generator script. The generator maps fields from the PRD front-matter to OpenAPI: title, paths (with method, path, summary), request/response schemas (minimal types), security (e.g., bearerAuth), and examples derived from acceptance criteria. Keep the generated file in the same feature folder as openapi.yaml so it’s obvious where the contract lives.

Run a lightweight linter (Spectral) and a mock server (Prism or Postman/Stoplight mock) in CI. The mock server provides a stable sandbox for frontend contractors or agent-based code generators while backend work proceeds. Tools like Prism or Postman support OpenAPI‑based mocking and let you iterate against a predictable contract.

Use your OpenAPI file to generate executable acceptance tests. There are two pragmatic approaches: (1) generate test cases directly from OpenAPI examples/schemas (many tools produce Jest/Cypress/Postman tests), or (2) run a contract validator against a running implementation. Tools like Dredd validate a live API against an OpenAPI spec and fail CI on mismatches — that’s the simplest way to ensure the implementation meets the contract.

For deeper contract-driven workflows, use tools that treat the spec as an executable contract (Specmatic or similar). These tools can spin up smart stubs and run contract tests during CI so integration failures are caught early. Add a breaking-change gate in CI to prevent accidental incompatible edits.

A JSON‑LD feature card is a compact, typed artifact that summarizes the canonical PRD + contract for downstream consumers: contractors, reviewers, CI agents, or code generators. The generator produces a small JSON‑LD file (features/<slug>/feature-card.jsonld) containing: id, title, short description, endpoints (with OpenAPI pointer), acceptanceCriteria (array of GIVEN/WHEN/THEN), owner, and relevant tags.

Keep the feature card intentionally minimal and machine-readable. Store pointers to the OpenAPI fragment using JSON Pointer or a documented path so consumers can dereference the exact schema. Agents or contractor scripts can read feature-card.jsonld to configure scaffolding, tests, or even generate task checklists automatically.

Add a lightweight CI pipeline that runs on PRs touching features/: steps: validate PRD front-matter, generate openapi.yaml, lint OpenAPI (Spectral), run contract tests or Dredd against a test instance, and produce the feature-card.jsonld artifact. If any step fails, block the PR. For iterative speed, run the generator locally via a dedicated NPM/Python script so engineers can preview outputs before committing.

Provide starter templates and a CLI command (e.g., appwispr spec:init <feature-slug>) that scaffolds the feature folder: README.prd.md with front-matter, openapi.yaml stub, and feature-card.jsonld template. Keep the templates minimal to avoid friction but explicit enough that acceptance criteria are testable.