Why

This section explain the motivation for designing a new specification language oriented towards requirement authoring. Three methodological foundation for the next-generation requirement-engineering, enabled by the req language, are presented.

Further details can be found on the design-goals scientific article available here.

Requirement-as-code

The IaC approach has become standard practice in DevOps; the equivalent for specifications barely exists. Software teams write specs in markdown, StrictDoc, or directly in code documentation. Systems engineers are turning to SysML v2, but for requirements themselves, database-backed tools like DOORS or Polarion remain the default.

Database-backed tools fall short of file-based workflows in one crucial respect: precise versioning and tracking. In software — and especially DevOps — git workflows track every commit and can trigger powerful automation. For requirements, that same data is locked inside a vendor tool, creating a hard dependency on (often legacy) software. That software is rarely usable without expert administrators and heavy custom scripting — DOORS’ DXL language being the prime example.

This is why requirements and specifications should be human-readable code — not Docx, not XML, not an ALM record.

Progressive formalization

A requirement must often serve both ends of the spectrum: formal and standardized enough for domain experts, yet still capturing a decision made by a non-technical stakeholder. No existing format follows a specification all the way from elicitation — initial, back-of-the-envelope writing — through to detailed design. Decisions end up scattered across files and databases, making alignment slower to understand and easier to get wrong.

req is designed for exactly that: start the specification in plain-text markdown and progressively refine it as the solution takes shape. Every level of abstraction and every formalism lives in the same set of source files. Modeling falls out of the specification process itself, as a byproduct of introducing glossary terms.

This keeps a single source of truth for the specification, one that can be dispatched to any downstream tool. It also brings real rigor to spec-driven workflows that plain text alone can’t provide.

Early defect diagnostics

Most defects in software and systems originate during the specification phase, from a misunderstanding between stakeholders. Agile workflows are no exception, and can make it worse: specifications are ephemeral, and recovering intent from archived tickets to understand what the system does is a common, painful example. That cost resurfaces at every test campaign and every deployment, and it is always higher than fixing the specification directly.

This is why req is designed to be statically analyzable as it is written, like a programming language — catching everything from phrasing issues to formal contradictions thanks to its progressively formal nature.