The requirement file
The requirement file
A requirement is a YAML file. One file holds exactly one requirement, and it lives in one of the requirement roots of the project. Here is a complete one from a small project:
$ cat requirements/RQM-1.yaml
schema: 1
uuid: "<uuid>"
id: "RQM-1"
kind: "functional"
title: "Users can sign in"
text: "A user who gives a valid name and password gets a session."
acceptance:
- "A valid name and password give a session."
- "A wrong password gives an error and no session."
verification: [test]
priority: "must"
status: "approved"
tests:
- "sessions::tests::sign_in_with_a_valid_password"
- "sessions::tests::sign_in_with_a_wrong_password"
fields:
area: "auth"
You will rarely write one from scratch. rqm create writes the file with the right shape and you edit it.
The keys
Eight keys are required, and the others are optional.
| Key | Required | What it holds |
|---|---|---|
schema |
yes | The version of the format. It is 1. |
uuid |
yes | The permanent identity of the requirement, a UUID of version 7. rqm create makes it. See Identity and hashes. |
id |
yes | The handle that people use, RQM- and a number: RQM-12. |
kind |
yes | The kind of requirement. It must be declared in rqm.yaml. See Kinds and fields. |
title |
yes | A short name, not empty. |
text |
yes | The requirement itself, not empty. |
acceptance |
yes | A list of criteria that say when the requirement is met. At least one. |
verification |
yes | How the requirement is verified: a list of at least one method from test, inspection, analysis and demonstration. |
evidence |
when a method other than test is used |
A description of the manual evidence for inspection, analysis or demonstration. |
status |
no | Where the requirement is in its life. draft when absent. |
priority |
no | must, should or may. It can be inherited. See Parents and inheritance. |
parent |
no | The requirement this one refines. |
links |
no | Other requirements this one relates to. |
tests |
no | The tests that verify the requirement. See Binding tests to requirements. |
owner, labels |
no | Who is responsible, and free labels. Both are just recorded. |
rationale, notes |
no | Why the requirement exists, and anything else worth saying. |
fields |
no | The values of the fields that the kind declares. |
Prose is Markdown that rqm does not interpret. title, text, the criteria of acceptance, evidence, rationale and notes are prose, and rqm does not care how you wrap or indent it. Spaces at the end of a line, and the difference between line endings, do not count as a change.
Status
The status records a decision about the requirement, and not whether it has been verified:
| Status | Meaning |
|---|---|
draft |
Being written. This is what rqm create gives. |
approved |
Agreed. |
required |
Agreed, and it must be verified. rqm check insists that a required requirement that is verified by test has a test bound to it. |
deprecated |
Kept for history, no longer applies. |
rejected |
Considered, and not accepted. |
Later releases use the status to decide what a failing or missing test means for each requirement. Today it is recorded and shown, and required is the only value that rqm check treats differently.
What rqm refuses
The reader is strict on purpose, because a file that is half understood is worse than a file that is refused. A key that is not in the table is an error. A kind field written at the top level, where it does not belong, gets a hint about where it goes:
$ rqm check
checked 3 requirements (loaded 3 of 4 discovered requirement files)
error[E-UNKNOWN-FIELD]: unknown field 'area'
--> requirements/RQM-2.yaml:12:1
= help: 'area' is a field of this kind, so it belongs under 'fields:'.
[exit 2]
A file with any error contributes nothing: rqm check says how many files it loaded out of how many it found, and the requirement of a broken file is absent from list and show until you fix it. Two other things are errors: a file with more than one YAML document, and a key that appears twice in the same mapping. YAML tags and merge keys (<<) are not supported either. The exact rules are in How rqm reads YAML.