The canonical form

The hash of a requirement is the hash of a deterministic text, its canonical form. The text is built from the parsed and resolved requirement and never from the file, so the YAML is only the input syntax. The form is internal to rqm and is not a published interface. It is pinned by the golden digests in crates/rqm/tests/canon/, and any change to it needs a new algorithm id.

The current algorithm id is blake3-256/canon-v1. It names the hash function (BLAKE3 with 256-bit output) and the version of this form. An artifact that was hashed under another id is stale. It is reported as such and its hashes are never reinterpreted.

The encoding

A canonical value is one of null, a boolean, a signed 64-bit integer, a string, a list or a map. There is no float, so no float formatting, precision or rounding behaviour can reach a hash.

Value Written as
null, true, false the words null, true and false
integer plain decimal: an optional -, then digits with no leading zero. No +, no _, no exponent.
string double quotes around the text, with the escapes below
list [, the items separated by ,, and ]
map {, the entries as "key":value separated by ,, and }, in byte order of the keys

There is no whitespace outside strings. Keys are ordered by the bytes of their UTF-8 form, so Z comes before a, a prefix comes before the longer key, and a non-ASCII key comes after every ASCII key that starts with an ASCII character.

Exactly these characters are escaped in a string: " as \", \ as \\, line feed, carriage return and tab as \n, \r and \t, and every other character below U+0020 as \u00xx with two lowercase hexadecimal digits. Every other character, including DEL, U+2028 and all non-ASCII characters, is written as its UTF-8 bytes. Unicode normalization is not applied here: prose is normalized before it gets here, and identifiers are ASCII.

Prose

The prose fields are title, text, the entries of acceptance, evidence, rationale and notes. Before a prose value enters the canonical form it is normalized, and two texts that differ only in the ways below have one canonical form and one hash.

  • The text is NFC-normalized, so the composed and the decomposed spelling of a letter are the same.
  • A line ending is a line feed. A carriage return followed by a line feed, and a lone carriage return, become a line feed.
  • Spaces and tabs at the end of every line are removed. This includes a line inside a fenced code block, a line that holds only white space and the last line of the text.

Nothing else changes. The final line feed of a block scalar stays, white space inside a line and at its start stays, and white space other than the space and the tab, such as a no-break space, stays.

Trailing white space is never an error and never moves a hash. The file hash (bytes_hash) still changes, because it covers the raw bytes. A consequence to know about: the Markdown hard line break written as two spaces at the end of a line is not part of the meaning of the text. Write a hard line break with a backslash at the end of the line, or with <br>. Both are visible, are hashed like any other text, and move the hash when added or removed.

Every other string, such as a kind name or a custom string field, is encoded as it is written, byte for byte. Identifiers are ASCII (see the rules for identifiers), so normalization can never merge two different identifiers.

Identifiers

Identifiers are ASCII: a requirement id, a UUID, a reference to either, and the selectors that name a test. A character outside ASCII in one of them is E-ID-NONASCII, reported at the identifier before its grammar is checked, so the author is told the cause and not only that the grammar did not match. This holds for letters that look like ASCII ones, such as a Cyrillic capital that resembles M. Because identifiers are ASCII, Unicode normalization can never make two different identifiers equal, and an identifier is hashed exactly as written.

Empty values

A list inside a list that has no items, as in acceptance: [a, []], has no meaning and is E-EMPTY-VALUE, reported once at the item. An empty list that is a whole field is not this error: an absent list and an empty list have the same canonical form.

The hash of a requirement

effective_hash is the hash of the canonical text of one map, written under the algorithm id blake3-256/canon-v1. The map has exactly these keys, and a key is always present:

Key Value
uuid the uuid of the requirement, as a string
kind the kind name
title, text the prose, normalized
acceptance a list of normalized prose strings, in the order written
verification the method names, sorted in byte order and without duplicates
priority null, or a resolved value (below) holding the priority name
parent null, or the uuid of the parent as a string
tests the selectors as written, sorted in byte order and without duplicates
links the uuids that the links name, sorted and without duplicates
fields a map with one entry for every normative field that the kind declares (below)

The table of which fields are normative is in crates/rqm/src/hash/normative.rs, and it is the only authority. schema, id, evidence, status, owner, labels, rationale and notes are not normative and are not in the map.

A resolved value is a map with three keys: value, source and from. source is own when the requirement wrote the value, inherited when it comes from an ancestor, and default when it comes from the project default or from the default declared for the field. from is the uuid of the ancestor for inherited and null otherwise. The source is part of the hash, so the same value written, inherited and defaulted are three different meanings, and a change of an ancestor’s value or of a default moves the hash of everything that took it.

References are hashed as uuids. A link or parent written as RQM-7 and one written as the uuid of that requirement give the same hash, and renaming a requirement moves nobody’s hash. A reference that the resolved set does not hold is E-REF-UNKNOWN, and nothing is hashed.

Custom fields. For every field that the kind of the requirement declares with normative: true, which is the default, fields has an entry under the field’s name. The entry is null when the requirement has no value for it, and a resolved value otherwise. A field declared with normative: false is left out. Integers are written by value, a string list keeps its order, and a string or an enum value is written as it is, byte for byte.

Presence. The table of the design holds. An absent field is a key whose value is null, and an optional string that is present and empty is "" and is different from null. An absent tests or links is the same as an empty one, and that is the one silent equivalence: no other two of absent, empty and a value give one hash, and an explicit null and a list inside a list are errors (E-NULL-FIELD and E-EMPTY-VALUE) that have no encoding. A list that a kind declares is a custom field and follows the rule for custom fields, so an absent one is null and is different from []. A consequence to know about: a kind that gains a normative field changes the hash of every requirement of that kind, because every such requirement now has the key. The policy fingerprint changes at the same time, so nothing is made stale that was not already.

Integers

An integer is hashed by its value, not by how it was written. 1000, 1_000, +1000 and 0x3E8 are one number and give one digest, because the contract is over what a requirement means, and no author should stale a record by choosing another spelling. The canonical form writes the value in plain decimal, with a minus sign for a negative number and no plus sign, no underscore and no leading zero.

Normative integers are signed 64-bit numbers. A value outside that range is E-INTEGER-RANGE and has no digest. A float is never hashed: in a normative field it is E-FLOAT-NORMATIVE, and the canonical value type has no float at all, so no float formatting can reach a hash.

Golden digests

The canonical form is pinned by the cases in crates/rqm/tests/canon/, one JSON file per case, read by crates/rqm/tests/canon_golden.rs. A case holds the YAML of a requirement, optionally the YAML of the other requirements it needs (others) and the project defaults (defaults), and then what rqm must make of it: canonical_utf8 and its base64, the blake3_256 digest and the algo, or expect_error with a diagnostic code in place of those. The error cases are an integer outside the signed 64-bit range, a whole number wider than 64 bits (E-INTEGER-RANGE, not a float) and a float in a normative field (E-FLOAT-NORMATIVE). model is the same canonical text as a JSON value, for reading. A case can say equals or differs_from another case, and that is how the rules above are pinned: NFC and NFD, LF and CRLF, 1000 and 1_000, trailing white space, duplicates in a set, and a reference written as an id and as a uuid are cases that must equal each other, and a different order of acceptance is a case that must differ.

The kinds that the cases use are in crates/rqm/tests/canon/kinds.yaml.

A case fails with the recorded and the new canonical text. If the change is meant, the fix has two parts in one commit: run the tests with RQM_BLESS=1, which rewrites the recorded values and is a switch of the tests only, and change ALGO_ID, so that records hashed under the old form become stale and are never read as the new one. If the change was not meant, undo it.