File Format Specification

Formal specification of the Requiem requirement file format.

Overview

Requiem requirements are stored as Markdown files with YAML frontmatter. This document provides the formal specification.

File Extension

.md (Markdown)

Character Encoding

UTF-8

Filename Format

{NAMESPACE-}*{KIND}-{ID}.md

Where:

NAMESPACE: Zero or more namespace segments (alphanumeric, hyphen-separated)
KIND: Alphanumeric requirement kind (e.g., USR, SYS)
ID: Positive integer (zero-padded to configured digits, default 3)

Examples:

USR-001.md
SYS-042.md
AUTH-USR-001.md
MOBILE-AUTH-LOGIN-SYS-005.md

Validation Rules:

Must end with .md
NAMESPACE segments: non-empty, alphanumeric plus hyphen
KIND: non-empty, alphanumeric
ID: positive integer (1 or more), may have leading zeros
Segments separated by single hyphen -
No consecutive hyphens --
No leading or trailing hyphens

File Structure

Requirements consist of three parts:

YAML Frontmatter: Metadata enclosed in --- delimiters
HRID Heading: First heading with HRID as first token
Markdown Body: Requirement text in CommonMark format

General Structure

---
<YAML frontmatter>
---
# <HRID> <Title>
<blank line optional>
<Markdown content>

Example

---
_version: '1'
uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
created: 2025-07-22T12:19:56.950194157Z
tags:
- authentication
- security
parents:
- uuid: 3fc6800c-5acc-457e-baf9-a29b42b663fd
  fingerprint: c4020419ead000e9b5f9cfd4ebf6192e73f905c27e6897548d8f6e12fd7f1356
  hrid: USR-001
---
# SYS-001 Email Validation

The system shall validate user email addresses according to RFC 5322.

Email validation must occur before account creation.

YAML Frontmatter

Delimiters

Opening delimiter: --- on first line
Closing delimiter: --- on its own line
Both required

Schema Version 1

Current version: 1

Required Fields

`_version`

Type: String (quoted)

Format: "1"

Purpose: Schema version for forward/backward compatibility

Validation:

Must be present
Must be string type (quoted in YAML)
Currently only "1" is valid

Example:

_version: '1'

`uuid`

Type: UUID (string format)

Format: UUID v4 (RFC 4122)

Purpose: Globally unique, stable identifier

Validation:

Must be present
Must be valid UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Should be generated with uuid::Uuid::new_v4() or equivalent
Must be unique across all requirements (globally)
Must never change after creation

Example:

uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a

`created`

Type: Timestamp (string format)

Format: ISO 8601 with timezone (RFC 3339)

Purpose: Requirement creation timestamp

Validation:

Must be present
Must be valid ISO 8601 timestamp
Must include timezone (use UTC: Z suffix)
Format: YYYY-MM-DDTHH:MM:SS.sssssssssZ

Example:

created: 2025-07-22T12:19:56.950194157Z

Notes:

Nanosecond precision supported
Timezone must be UTC (Z suffix)
Set once at creation; never modified

Optional Fields

`tags`

Type: Array of strings

Format: YAML list

Purpose: Categorize and tag requirements

Validation:

Optional (omit if no tags)
Array elements must be strings
Empty array allowed but should be omitted
No duplicate tags within same requirement
Tags are case-sensitive

Example:

tags:
- authentication
- security
- high-priority

Omission:

# No tags field = no tags
_version: '1'
uuid: ...
# tags field omitted

Serialization:

Include only if non-empty: skip_serializing_if = "BTreeSet::is_empty"
Stored as BTreeSet internally (sorted, unique)

`parents`

Type: Array of parent objects

Format: YAML list of objects

Purpose: Link to parent (upstream) requirements

Validation:

Optional (omit if no parents, e.g., root requirements)
Array elements must be parent objects (see Parent Object Schema)
Empty array allowed but should be omitted
Duplicate parent UUIDs allowed (though unusual)

Example:

parents:
- uuid: 3fc6800c-5acc-457e-baf9-a29b42b663fd
  fingerprint: c4020419ead000e9b5f9cfd4ebf6192e73f905c27e6897548d8f6e12fd7f1356
  hrid: USR-001
- uuid: 7a8f9e2b-1c3d-4e5f-6a7b-8c9d0e1f2a3b
  fingerprint: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
  hrid: USR-003

Omission:

# No parents field = no parents (root requirement)
_version: '1'
uuid: ...
# parents field omitted

Serialization:

Include only if non-empty: skip_serializing_if = "Vec::is_empty"

Parent Object Schema

Each parent object has three fields:

`uuid`

Type: UUID (string format)

Format: UUID v4

Purpose: Stable reference to parent requirement

Validation:

Must be present in parent object
Must be valid UUID format
Should match uuid field of an existing requirement

Example:

uuid: 3fc6800c-5acc-457e-baf9-a29b42b663fd

`fingerprint`

Type: String (hex-encoded SHA256 hash)

Format: 64-character hexadecimal string

Purpose: Content hash of parent for change detection

Validation:

Must be present in parent object
Must be 64-character hexadecimal string
Generated by hashing parent's content and tags with SHA256

Example:

fingerprint: c4020419ead000e9b5f9cfd4ebf6192e73f905c27e6897548d8f6e12fd7f1356

Generation:

1. Collect parent's content (markdown body) and tags
2. Serialize with Borsh encoding
3. Hash with SHA256
4. Encode as hexadecimal string (64 characters)

`hrid`

Type: String (HRID format)

Format: {NAMESPACE-}*{KIND}-{ID}

Purpose: Human-readable reference to parent (convenience field)

Validation:

Must be present in parent object
Must be valid HRID format
Should match parent's filename (without .md extension)

Example:

hrid: USR-001

Notes:

Convenience field for human readability
May become outdated if parent is renamed
Corrected by req clean command
UUID is authoritative; HRID is informational

Schema Evolution

Future schema versions (e.g., _version: "2") will be backward-compatible:

New optional fields may be added
Required fields will not be removed
Field semantics will not change incompatibly

Parsers should:

Ignore unknown fields
Provide defaults for missing optional fields
Reject unknown _version values (fail-safe)

HRID Heading

Format

The first heading in the markdown must contain the HRID as the first token:

# <HRID> <Title Text>

Requirements

Must be a level-1 heading (#)
HRID must be the first token (word)
Followed by space and title text
HRID must match the filename (without .md)

Examples

# USR-001 Plain Text Storage
# SYS-042 Email Validation System
# AUTH-LOGIN-SYS-001 Password Hashing

Rationale

The HRID is stored in the heading (not frontmatter) for compatibility with Sphinx and MdBook, which use the first heading as the page title.

Markdown Body

Format

CommonMark (Markdown specification)

Location

Everything after the first heading is the markdown body.

Content

Free-form Markdown:

Headings (##, ###, etc. - first # is reserved for HRID)
Paragraphs
Lists (ordered, unordered)
Code blocks (fenced, indented)
Emphasis (bold, italic)
Links
Images
Blockquotes
Tables
Any CommonMark-compliant content

Whitespace

Leading/trailing whitespace: preserved
Empty lines between frontmatter and body: ignored
Empty body: valid (empty string)

Example

---
_version: '1'
uuid: ...
created: ...
---
# USR-001 Email Validation

The system shall validate user email addresses.

## Rationale

Email validation ensures...

## Acceptance Criteria

- Valid email format
- Rejects invalid emails
- Provides clear error messages

Parsing Rules

Frontmatter Parsing

First line must be ---
Read lines until next --- on its own line
Parse collected lines as YAML
Validate against schema
Remaining lines are markdown body

Error Handling

Missing opening delimiter:

Error: Expected frontmatter starting with '---'

Missing closing delimiter:

Error: Unexpected EOF while parsing frontmatter

Invalid YAML:

Error: Failed to parse YAML: <syntax error details>

Missing required field:

Error: Missing required field '<field_name>'

Invalid UUID format:

Error: Invalid UUID format: '<value>'

Invalid timestamp format:

Error: Invalid timestamp format: '<value>'

Unknown _version:

Error: Unknown schema version: '<value>'

Strict vs. Permissive

Requiem parsing is strict by default:

All required fields must be present
All fields must be valid
Unknown fields in schema version 1 cause errors (currently)

Controlled by allow_invalid config option:

allow_invalid = false (default): Strict parsing, fail on errors
allow_invalid = true: Skip invalid requirements with warnings

Serialization Rules

Field Order

Fields serialized in this order:

_version
uuid
created
tags (if present)
parents (if present)

Omission Rules

tags: Omitted if empty
parents: Omitted if empty

Formatting

YAML indentation: 2 spaces
String quoting: Single quotes for strings containing special characters
Array formatting: One element per line with - prefix
Object formatting: Indented key-value pairs

Example Output

---
_version: '1'
uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
created: 2025-07-22T12:19:56.950194157Z
tags:
- authentication
- security
parents:
- uuid: 3fc6800c-5acc-457e-baf9-a29b42b663fd
  fingerprint: c4020419ead000e9b5f9cfd4ebf6192e73f905c27e6897548d8f6e12fd7f1356
  hrid: USR-001
---

Requirement text here.

Validation

Syntactic Validation

Valid YAML frontmatter
Valid Markdown body (CommonMark)
Correct delimiters

Semantic Validation

Required fields present
Field types correct
UUID format valid
Timestamp format valid
HRID format valid (in parent references)
Fingerprint format valid (64-char hex)

Referential Integrity

Parent UUIDs reference existing requirements
No self-references (requirement is not its own parent)
No duplicate UUIDs across all requirements

Configuration-Based Validation

HRID KIND in allowed_kinds (if configured)
File follows naming convention (if allow_unrecognised = false)

Canonical Example

---
_version: '1'
uuid: 4bfeb7d5-d168-44a7-b0f1-e292c1c89b9a
created: 2025-07-22T12:19:56.950194157Z
tags:
- authentication
- security
- high-priority
parents:
- uuid: 3fc6800c-5acc-457e-baf9-a29b42b663fd
  fingerprint: c4020419ead000e9b5f9cfd4ebf6192e73f905c27e6897548d8f6e12fd7f1356
  hrid: USR-001
- uuid: 7a8f9e2b-1c3d-4e5f-6a7b-8c9d0e1f2a3b
  fingerprint: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
  hrid: USR-003
---
# SYS-001 Email Validation

The system shall validate user email addresses according to RFC 5322.

## Rationale

Email validation ensures that user accounts can be contacted and that
authentication tokens can be delivered reliably.

## Acceptance Criteria

- Email addresses must match RFC 5322 format
- Invalid email addresses must be rejected with clear error message
- Validation must occur before account creation

## References

- RFC 5322: Internet Message Format
- OWASP Email Validation Guidelines

Summary

File format:

Markdown (.md) files with UTF-8 encoding
YAML frontmatter enclosed in --- delimiters
CommonMark markdown body

Required frontmatter fields:

_version: Schema version (currently "1")
uuid: Unique identifier (UUID v4)
created: Creation timestamp (ISO 8601 with UTC)

Optional frontmatter fields:

tags: Array of tags
parents: Array of parent objects (uuid, fingerprint, hrid)

Validation:

Strict by default
Controlled by allow_invalid config option
Includes syntactic, semantic, and referential checks

Next Steps

See CLI Command Reference for working with requirements
See Configuration Reference for config options
Review Working with Requirements for practical examples

Keyboard shortcuts

Requiem User Guide