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.