Kinds and fields
Kinds and fields
Every requirement has a kind, and a project declares the kinds it uses in the kinds section of rqm.yaml. A kind is a name, such as functional or constraint, and a kind can declare fields that its requirements carry in addition to the ones every requirement has.
The smallest declaration is a kind with no fields, which is what rqm init writes for the default kind:
kinds:
functional: {}
Declaring fields
This project’s kinds are more useful. A functional requirement must say which area of the system it belongs to, and a constraint needs nothing:
kinds:
functional:
requires: ["area"]
fields:
area:
type: "enum"
values: ["auth", "sessions", "audit"]
constraint: {}
A kind has two keys, both optional. fields declares the fields, and requires lists the names of the fields that a requirement of this kind must have a value for. A field in requires that is not declared is an error.
A kind name and a field name are lowercase words: a letter, then lowercase letters, digits and _, at most 64 characters.
A field is declared with these keys:
| Key | What it says |
|---|---|
type |
string, integer, bool, enum or string-list. |
values |
The allowed values of an enum, and only for an enum. |
required |
Whether a requirement must have a value. The same as listing the field in requires. |
default |
The value a requirement has when it does not write one. |
inheritable |
Whether a requirement without a value takes the one of its nearest ancestor. See Parents and inheritance. |
normative |
Whether the field counts as part of the meaning of the requirement. It does unless you say false. See Identity and hashes. |
An integer is a whole number in the signed 64-bit range. There are no floating-point fields, because a hash of the meaning must not depend on how a number is written.
Writing a field in a requirement
The values go under fields: in the requirement, and not next to title and text. That keeps the fields that every requirement has apart from the ones that your project invented, so a new core key can never collide with a field of yours.
fields:
area: "auth"
rqm create --field area=auth writes it. The reader checks the value against the declaration, and the message says what was expected:
$ rqm check
checked 3 requirements (loaded 3 of 4 discovered requirement files)
error[E-FIELD-VALUE]: The field 'area' must be one of auth, sessions, audit, found 'billing'
--> requirements/RQM-4.yaml:14:9
[exit 2]
Adding a value to an enum is an edit of rqm.yaml, and does not touch any requirement.