74 lines
3.9 KiB
Markdown
74 lines
3.9 KiB
Markdown
# 4. Identity
|
|
|
|
A node's ID is a name, not a position.
|
|
It carries no meaning, and once a document is established it is never recomputed, reassigned or reused.
|
|
|
|
## 4.1 Letter-first base32
|
|
|
|
To encode a SHA-256 digest *d* (32 bytes) as a letter-first ID of *n* characters:
|
|
|
|
1. The first character is the letter at index `d[0] mod 22` of `abcdefghjkmnpqrstvwxyz`.
|
|
2. Read the bytes `d[1]` to `d[31]` as one big-endian bit string.
|
|
3. Each further character is the Crockford character for the next five bits, from the most significant end.
|
|
|
|
Node IDs have seven characters, about 34.5 bits; derived record IDs have 13.
|
|
`ids.jsonl` in the vectors gives digests and their encodings.
|
|
|
|
## 4.2 Minting node IDs
|
|
|
|
A node's ID is minted from SHA-256 of the canonical JSON of the array `["scienting-id/1", doc_key, kind, text_hash, occurrence]`, encoded with seven characters.
|
|
`text_hash` is the plain, never keyed, text hash of the node ([5.1](05-hashes.md#51-the-five-values)).
|
|
|
|
When a document is established, nodes are minted in document order.
|
|
A node's occurrence starts at the number of earlier nodes with the same kind and text hash; while the resulting ID is already taken, the occurrence increases by one.
|
|
So a fresh conversion of the same input mints the same IDs.
|
|
|
|
A node added later, by an `insert` or a `split`, starts at occurrence 0 and increases while the ID is taken by any live, retired or alias ID of the document.
|
|
|
|
Columns and figure-text items are not nodes, but they take IDs from the same rule and the same document-wide set, after the nodes:
|
|
a column with kind `column` and the text hash of its header cells' plain projections joined with U+0020;
|
|
a figure-text item with kind `figure-text` and the text hash of its text.
|
|
|
|
## 4.3 Permanence, retirement and aliases
|
|
|
|
| Rule | Detail |
|
|
| --- | --- |
|
|
| Permanence | Once established, an ID never changes, and no other node ever takes it. |
|
|
| Retirement | A `merge` or a `delete` retires IDs ([11](11-corrections.md)). A merge records the surviving node as the successor; a delete records none. |
|
|
| Aliases | Legacy IDs, such as the `b-p03-text-004` block IDs an earlier extract format used, are recorded as aliases of the node that now holds that text. |
|
|
| Labels | What people say, such as "Eq. 3" or "Table S1", is a `label`, never an ID. |
|
|
| Display paths | Tools may show a path such as `§2.3 ¶4 s2`; it is never stored or cited. |
|
|
|
|
## 4.4 `ids.jsonl`
|
|
|
|
Each line is one entry.
|
|
|
|
| Property | Holds |
|
|
| --- | --- |
|
|
| `id` | The retired node ID, or the alias. |
|
|
| `kind` | `retired` or `alias`. |
|
|
| `successor` | For a retirement, the successor's ID, or null for a deletion; for an alias, the live node it names. |
|
|
| `node_kind` | For a retirement, the kind the node had. |
|
|
| `rev` | For a retirement, the index of the correction that retired it. |
|
|
|
|
Aliases come first, sorted by ID; retirements follow, sorted by `rev` and then ID.
|
|
No ID is both live and in the table, every successor is live or itself in the table, and every alias names a live node.
|
|
|
|
## 4.5 Store-qualified names
|
|
|
|
A document key qualified by its store, `smithlab/cornell1995second`, names a document anywhere, and an address with a store names a node anywhere ([6.1](06-anchors.md#61-addresses)).
|
|
|
|
## 4.6 Record IDs
|
|
|
|
A record that is never edited takes its ID from its own content, as 13 letter-first characters of a hash:
|
|
|
|
| Record | Hash |
|
|
| --- | --- |
|
|
| Receipt, revocation, policy | The record hash: SHA-256 of the record without `id` and `signature` ([8.4](08-fidelity.md#84-record-hashes-and-signatures)). |
|
|
| Correction | SHA-256 of the record without `id`. |
|
|
| Annotation | SHA-256 of the annotation without `id`, `status`, `receipt` and `modified`, as created. |
|
|
| Submission, digitization | SHA-256 of the record without `id`. |
|
|
|
|
A witness ID is the seven-character letter-first encoding of the witness's SHA-256 itself.
|
|
Other records, such as layers and qa reports, MAY use any record ID unique in their store.
|