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.