Identity and hashes
Identity and hashes
A requirement has two names, and the file of a requirement has two hashes. This page explains what each is for.
The id and the uuid
The id, such as RQM-12, is the name people use: in conversation, in commit messages, in parent and links, and as the argument of rqm show. It is written as a prefix (such as RQM), a hyphen, and a whole number without leading zeros. The prefix is an uppercase ASCII letter followed by up to 15 more uppercase ASCII letters or digits. Projects declare the prefixes they use in their configuration, and RQM is the default. rqm create gives a new requirement the next number for its prefix, and numbers are not reused as long as the file of the old requirement stays in the project.
The uuid is the identity of the requirement. It is a UUID of version 7, which contains the time the requirement was created and random bits, and rqm create makes it. It never changes and it is never reused. Nobody types it, but anything that must keep pointing at the same requirement, now and in the future, can use it. rqm show accepts it, and so do parent and links.
The id is a handle and the uuid is the identity. If you change the id of a requirement by editing its file, a reference that used the old id stops resolving (E-REF-UNKNOWN) and one that used the uuid keeps working. Neither is allowed to be shared: two files with the same id or the same uuid are both refused, and each diagnostic names the other file (E-ID-DUPLICATE, E-UUID-DUPLICATE).
Identifiers are ASCII. A character outside ASCII in an id, a uuid or a reference is refused at that character, so two identifiers that look the same on screen can never be different.
The two hashes
rqm show prints two hashes of a requirement:
bytesis the hash of the bytes of the file. It changes whenever the file does, even for a change that means nothing, such as re-indenting the YAML.effectiveis the hash of the meaning of the requirement: what the file says after it has been read and resolved. Formatting does not change it: the order of keys, quotes, the YAML style and the end of lines have no effect. It does change when a value changes, and also when something the requirement inherits changes, as when the priority of a parent moves.
The effective hash is the one that matters. Evidence about a requirement, such as the result of a test, is only worth something for the requirement as it was when the evidence was produced, and the hash is how rqm tells a requirement that is the same from one that changed. Later releases record it with the evidence, and compare.
A field of a kind that is declared normative: false is shown and kept, and it is left out of the meaning, so changing it moves bytes and leaves effective alone. That is the way to have notes and bookkeeping on a requirement that must not make its evidence stale.
The hash function is BLAKE3 with a 256-bit output, and the exact definition of the meaning, the canonical form, is in The canonical form and hashes. The hashes in this book are replaced by <hash> in the examples, because they depend on the exact text of each file.