.sysreq is Specy’s concrete syntax for system requirements. It is a small DSL, deliberately terse, designed to read like an EARS document with enough structure for tooling to parse. A requirement set is opened by a requirements declaration scoped to a bounded context or to the organization; each requirement inside carries an ID, a name, a pattern, a rationale, an EARS statement, and a priority. This page shows the full DSL, enumerates the syntax rules, and fixes the conventions for prd-source paths and source strings.

A Full Example

The DSL opens with a requirements block, declares its scope, and optionally points upstream at the PRD it was derived from. Each requirement follows a fixed shape: ID, name, pattern, optional rationale, EARS statement, priority, optional dependency and conflict links, and optional free-text source.

In every EARS statement below, “the system” refers to the software system(s) of the bounded context named in the enclosing scoped-to clause. A requirement set scoped-to OrderContext produces EARS sentences about OrderContext’s systems; one scoped-to PaymentContext produces sentences about PaymentContext’s systems. The noun “the system” is never global — it is always the systems of exactly one bounded context.

Example:

requirements "Order Processing" scoped-to OrderContext {
  prd-source "specs/order.prd"

  REQ-ORD-001 "Order line quantity floor" : ubiquitous
    :: "Regulatory minimum — trade compliance requires explicit quantity"
    "The system shall reject order lines with a quantity less than one."
    priority must

  REQ-ORD-002 "Order placement" : event-driven
    :: "Core revenue path — every sale starts here"
    "When a customer submits an order, the system shall create
     the order in draft status and emit an OrderPlaced event."
    priority must

  REQ-ORD-003 "Active customer guard" : state-driven
    :: "Suspended customers must not accumulate new debt"
    "While the customer is suspended, the system shall reject
     new orders."
    priority must

  REQ-ORD-004 "Insufficient stock handling" : unwanted
    :: "Overselling erodes trust — hard lesson from Q3 2024"
    "If the ordered product is out of stock, then the system shall
     reject the order and notify the customer."
    priority must

  REQ-ORD-005 "Credit limit agreement" : complex
    :: "Finance requires real-time credit exposure control"
    "While the customer has an active credit account, when an order
     is placed, if the order total exceeds the remaining credit limit,
     then the system shall hold the order for manual approval."
    priority should

  REQ-ORD-006 "Express shipping option" : optional
    :: "Premium feature — only for regions with courier partnerships"
    "Where express shipping is available, the system shall offer
     same-day delivery for orders placed before noon."
    priority could

  REQ-ORD-007 "Order confirmation" : event-driven
    depends-on REQ-ORD-002
    source "PRD v2.1 §3.4 — Payment-gated order flow"
    "When payment is verified, the system shall confirm the order."
    priority must

  REQ-ORD-008 "Immediate fulfillment" : event-driven
    conflicts-with REQ-ORD-005
    :: "Ops wants auto-ship; Finance wants credit hold — resolved by priority"
    "When an order is confirmed, the system shall immediately
     initiate fulfillment."
    priority should
}

Syntax Rules

The DSL has a small number of rules. Each is load-bearing — the tooling relies on them to parse, validate, and connect the .sysreq to its upstream .prd and downstream .domain.

  • requirements "<name>" scoped-to <BoundedContext> opens a requirement set. The scope target is a bounded context for functional requirements and the organization for cross-cutting NFRs (see Non-Functional Requirements).
  • prd-source "<relative-path>" optionally declares the path to the .prd file that originated the set’s requirements. Path is relative to the .sysreq file’s location. When present, source strings on individual requirements reference elements inside this file. Multiple prd-source declarations are allowed when product requirements span several files.
  • Each requirement starts with its id (REQ-<BC>-NNN), followed by its name in quotes, a colon, and its pattern (ubiquitous, state-driven, event-driven, unwanted, optional, or complex).
  • :: introduces the rationale — the same operator used on domain constructs. Rationale is free text in quotes.
  • The EARS statement follows in quotes, on one or more lines. Line breaks inside the statement are whitespace-equivalent; the parser reassembles them into a single sentence.
  • priority declares the MoSCoW level (must, should, could, wont). Exactly one per requirement.
  • source "<reference>" optionally declares the upstream provenance — a PRD section, user story ID, regulatory clause, or business goal.

The order of optional clauses (::, source, depends-on, conflicts-with, decomposed-into) is not significant to the parser but conventionally appears before the EARS statement. The EARS statement itself always precedes priority.

Example: The full requirement set in the previous section exercises every rule. A minimal requirement with only the required elements is:

REQ-ORD-001 "Order line quantity floor" : ubiquitous
  "The system shall reject order lines with a quantity less than one."
  priority must

Dependencies & Conflicts

Requirements may declare relationships to other requirements inline. depends-on <ID> expresses a logical prerequisite — the dependent requirement cannot be satisfied unless the target is. conflicts-with <ID> expresses an explicit tension and requires a documented resolution (typically in the rationale). Both clauses accept multiple IDs.

Example:

REQ-ORD-007 "Order confirmation" : event-driven
  depends-on REQ-ORD-002
  source "PRD v2.1 §3.4 — Payment-gated order flow"
  "When payment is verified, the system shall confirm the order."
  priority must

REQ-ORD-008 "Immediate fulfillment" : event-driven
  conflicts-with REQ-ORD-005
  :: "Ops wants auto-ship; Finance wants credit hold — resolved by priority"
  "When an order is confirmed, the system shall immediately
   initiate fulfillment."
  priority should

decomposed-into { ID, ID, ... } is the third relational clause and is most commonly used on organization-scoped cross-cutting NFRs; see Non-Functional Requirements.

prd-source Path Convention

The prd-source path is always relative to the location of the .sysreq file. This keeps the provenance chain portable: if the specs directory is moved as a whole, every cross-file reference continues to resolve. Absolute paths are rejected by convention; URL references are reserved for future use.

Typical layouts put .prd and .sysreq files side by side in a specs/ directory:

repo/
  specs/
    order.prd
    order.sysreq        prd-source "order.prd"
    payment.prd
    payment.sysreq      prd-source "payment.prd"

When product requirements span multiple PRDs (for example, a platform PRD plus a feature PRD), declare prd-source twice:

requirements "Order Processing" scoped-to OrderContext {
  prd-source "platform.prd"
  prd-source "order.prd"
  // ...
}

Example: Combined with the domain side’s requirements-source, the three-file chain becomes file-resolvable end to end: specs/order.domain → requirements-source "order.sysreq" → prd-source "order.prd". See Traceability for the full chain and PRD Releases & Traceability for the PRD side.

source String Conventions

The source field is free-text by design — it must survive PRD schema evolution, tool migrations, and decades-long regulatory references. What it gains in flexibility it relies on convention to keep consistent. Four families of conventions cover the common cases:

  • Feature + acceptance criterion — "Feature: Checkout — AC: payment-gated confirmation". Matches the feature/AC structure of a .prd file.
  • User story ID — "US-347", optionally followed by a short title: "US-347 — Credit-limit hold". Useful when PRDs reference an external tracker.
  • Business goal — "Goal: reduce chargebacks by 30%". Traceable to a goal statement in the PRD.
  • Regulation or external clause — "Regulation: PCI-DSS 4.0 §3.2.1", "Standard: WCAG 2.1 AA", "Contract: Acme MSA §4.2". Traceable to an external document that the PRD itself references.

Additional conventions are acceptable as long as they are consistent within a .prd/.sysreq pair. The only hard rule is that source must be resolvable: a human, or a tool, following prd-source and reading the PRD, must be able to locate the referenced element.

Example:

REQ-ORD-007 "Order confirmation" : event-driven
  depends-on REQ-ORD-002
  source "PRD v2.1 §3.4 — Payment-gated order flow"
  "When payment is verified, the system shall confirm the order."
  priority must

REQ-NFR-004 "Cardholder data retention" : ubiquitous
  source "Regulation: PCI-DSS 4.0 §3.2.1"
  "The system shall not retain sensitive authentication data after
   authorization, even if encrypted."
  priority must