Skip to content
contextlint

REF-002 ID definitions and references

Overview

Section titled “Overview”

Validates that IDs declared in a definition file (such as a requirements doc) and references from other files (such as test plans or design docs) are consistent in both directions. This is a project-scope rule and is evaluated across all documents loaded via include.

  • ID referenced but not defined → error
  • ID defined but never referenced → warning

Why it matters

Section titled “Why it matters”

Requirement IDs are typically declared in a definition file (e.g. requirements.md) and referenced from test, design, and implementation documents. When a requirement is renamed or removed, referring documents do not update automatically. Conversely, a defined requirement that is referenced from nowhere may not be wired up to any implementation or test. This rule validates traceability in both directions mechanically.

Options

Section titled “Options”
FieldTypeRequiredDescription
definitionsstringYesGlob of files that declare IDs
referencesstring[]YesArray of globs for files that reference IDs
idColumnstringYesColumn name that holds the ID in the definition file
idPatternstringYesRegex of values to treat as IDs

idPattern is applied both to column values in definition tables and to text tokens in reference documents. Because it scans plain text too, including an explicit prefix (such as ^REQ-) is the safest way to avoid accidentally matching unrelated words.

Bad example

Section titled “Bad example”
docs/requirements.md:
| ID     | Description       |
| ------ | ----------------- |
| REQ-01 | User registration |
| REQ-02 | Password reset    |


docs/tests.md:
- Test for REQ-01 ...
- Test for REQ-99 ...

REQ-99 is not defined, which is an error. REQ-02 is never referenced, which is a warning.

docs/tests.md
  line 2  error  ID "REQ-99" is referenced but not defined in any definition file  REF-002


docs/requirements.md
  line 4  warning  ID "REQ-02" is defined but never referenced  REF-002

After fix

Section titled “After fix”

Replace the undefined REQ-99 with REQ-02 so that REQ-02 is referenced.

docs/tests.md:
- Test for REQ-01 ...
- Test for REQ-02 ...

Configuration example

Section titled “Configuration example”
{
  "rule": "ref002",
  "options": {
    "definitions": "**/requirements.md",
    "references": ["**/tests.md", "**/design.md"],
    "idColumn": "ID",
    "idPattern": "^REQ-\\d+$"
  }
}
Section titled “Related rules”