summaryrefslogtreecommitdiffhomepage
path: root/ssp-format-specification.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-25 22:28:50 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-03 21:50:59 -0400
commit5a5036e53aa18afa61d6e475336cd96c115dac00 (patch)
tree669a9190703b6833591311c73f4646a123c11dc3 /ssp-format-specification.md
parent.ocda.db specified & the two serialisations agree (diff)
derived values that the model left unstated
The model says nothing about an object's identifier or its anchor, and both are derived: the identifier is the ocn where there is one, the anchor is the segment name. The .ssp omits each where it can be worked out; the .ocda.db states both on every row. This is existing behaviour, not a new rule. Spine's own .ssp reader has always filled both in, which is why the database carries them: the database is written from the .ssp read straight back. It should have been written down first. Two readers written independently from these documents disagreed for want of it, on nearly every object, and nothing short of comparing whole models showed it. ocda-model.md gains 3.1 the identifier, 7.1 the anchor and 9 derived values, with the loading rule in a table; "what the model does not hold" becomes 10. The two format specifications gain what a reader needs and did not have: - the .ssp's property table now says what the absent value is, not only when it is written; - the .ocda.db gains 3.2.1, the metadata key prefix that carries what the .ssp puts in four blocks, which a reader must strip to give one model from either file, and the note that a value here may carry whitespace the text form cannot represent; - 3.3 gains the element types of each JSON column and a warning to parse rather than scan: the encoder writes "/" as "\/" and every document in the reference collection has a heading containing one; - 4.1 names the three places the two files are not symmetric, including translation.ocn_aligned, which a .ssp cannot hold because it is one language, and which a reader should keep out of the document model so that nothing built on the model can tell which file it was given. (assisted by Claude-Code)
Diffstat (limited to 'ssp-format-specification.md')
-rw-r--r--ssp-format-specification.md97
1 files changed, 53 insertions, 44 deletions
diff --git a/ssp-format-specification.md b/ssp-format-specification.md
index 17974a3..ae1ecaf 100644
--- a/ssp-format-specification.md
+++ b/ssp-format-specification.md
@@ -338,6 +338,15 @@ reference collection), and then its identifier, when it has one
that is not simply the ocn. Every other kind carries an identifier, on the
same condition, as the `.identifier` property.
+> **A reader must derive the identifier where it is absent, and the anchor
+> likewise.** "when it has one that is not simply the ocn" means the
+> identifier *is* the ocn in every other case, and a reader that leaves the
+> field empty gives a different model from the one the `.ocda.db` gives, on
+> nearly every object. Section 9 of [`ocda-model.md`](ocda-model.md) states
+> both derivations and why they belong to the model rather than to either
+> format. Two readers written independently from these documents disagreed
+> for want of it.
+
### 6.2 Text lines
```
@@ -373,50 +382,50 @@ In the table, "emitted when" is the condition under which the property
appears at all. Counts are occurrences across the 36 document reference
set, as a guide to which parts of the format are load bearing.
-| # | property | value | emitted when | count |
-|----|---------------------------|-------------------------------|-------------------------------------------------------------|--------|
-| 1 | `.identifier` | string | a non-heading has an identifier that is not its ocn | 353 |
-| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 56,882 |
-| 3 | `.section` | string | the object's own section differs from the block it sits in | 605 |
-| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,631 |
-| 5 | `.last_descendant` | int | non-zero: the last ocn under this heading | 3,202 |
-| 6 | `.children` | ints | the heading has child headings | 827 |
-| 7 | `.ancestors` | 8 ints | any is non-zero | 53,595 |
-| 8 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,595 |
-| 9 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
-| 10 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
-| 11 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
-| 12 | `.parent_lev` | int | non-zero | 52,848 |
-| 13 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
-| 14 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
-| 15 | `.is_of_type` | string | always, in practice | 56,882 |
-| 16 | `.attrib` | string | set | 1 |
-| 17 | `.meta_lang` | string | the object carries its own language | 0 |
-| 18 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
-| 19 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
-| 20 | `.image` | record | once **per image**, in order of appearance | 63 |
-| 21 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
-| 22 | `.bullet` | `true` | the object is a bullet item | 1,903 |
-| 23 | `.lang` | string | the text attributes carry a language | 0 |
-| 24 | `.has` | flags | any is set | 11,143 |
-| 25 | `.table_cols` | int | the object is a table with columns | 32 |
-| 26 | `.table_widths` | ints | the table has column widths | 32 |
-| 27 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
-| 28 | `.table_header` | `true` | the table has a header row | 29 |
-| 29 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
-| 30 | `.stow_link` | url | once **per extracted link** | 1,013 |
-| 31 | `.segment` | string | the heading opens a segment | 3,355 |
-| 32 | `.anchor` | string | the anchor differs from the segment name | 68 |
-| 33 | `.segment_prev` | string | there is a previous segment | 1,022 |
-| 34 | `.segment_next` | string | there is a next segment | 1,022 |
-| 35 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
-| 36 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
-| 37 | `.segment_html_is` | string | the object is inside an html segment | 47,024 |
-| 38 | `.segment_epub_is` | string | the object is inside an epub segment | 47,024 |
-| 39 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
-| 40 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
-| 41 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
-| 42 | `.anchor_tag` | string | once **per anchor tag** | 7,883 |
+| # | property | value | emitted when | count |
+|----|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------|--------|
+| 1 | `.identifier` | string | a non-heading has an identifier that is not its ocn (**otherwise it is the ocn**: model section 9) | 353 |
+| 2 | `.part` | string | the object belongs to a part (`frontmatter`, `body`, ...) | 56,882 |
+| 3 | `.section` | string | the object's own section differs from the block it sits in | 605 |
+| 4 | `.parent` | int | **every object except** the document root and `toc` entries | 53,631 |
+| 5 | `.last_descendant` | int | non-zero: the last ocn under this heading | 3,202 |
+| 6 | `.children` | ints | the heading has child headings | 827 |
+| 7 | `.ancestors` | 8 ints | any is non-zero | 53,595 |
+| 8 | `.ancestors_collapsed` | 8 ints | any is non-zero | 53,595 |
+| 9 | `.dom_status` | 8 ints | any is non-zero | 3,319 |
+| 10 | `.dom_status_collapsed` | 8 ints | any is non-zero | 3,319 |
+| 11 | `.heading_lev_collapsed` | int | it is below 9 | 3,503 |
+| 12 | `.parent_lev` | int | non-zero | 52,848 |
+| 13 | `.dummy` | `true` | the heading was introduced to segment an output | 183 |
+| 14 | `.ocn_off` | `true` | the object has no citation number | 7,543 |
+| 15 | `.is_of_type` | string | always, in practice | 56,882 |
+| 16 | `.attrib` | string | set | 1 |
+| 17 | `.meta_lang` | string | the object carries its own language | 0 |
+| 18 | `.meta_syntax` | string | the object carries its own markup syntax | 0 |
+| 19 | `.sha256` | hex | the object's text digest is non-zero | 51,253 |
+| 20 | `.image` | record | once **per image**, in order of appearance | 63 |
+| 21 | `.indent` | 2 ints | either indent is non-zero: `base hang` | 7,583 |
+| 22 | `.bullet` | `true` | the object is a bullet item | 1,903 |
+| 23 | `.lang` | string | the text attributes carry a language | 0 |
+| 24 | `.has` | flags | any is set | 11,143 |
+| 25 | `.table_cols` | int | the object is a table with columns | 32 |
+| 26 | `.table_widths` | ints | the table has column widths | 32 |
+| 27 | `.table_aligns` | letters | the table has alignments (`l` `c` `r`) | 32 |
+| 28 | `.table_header` | `true` | the table has a header row | 29 |
+| 29 | `.code_linenumbers` | `true` | the code block is numbered | 1 |
+| 30 | `.stow_link` | url | once **per extracted link** | 1,013 |
+| 31 | `.segment` | string | the heading opens a segment | 3,355 |
+| 32 | `.anchor` | string | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9) | 68 |
+| 33 | `.segment_prev` | string | there is a previous segment | 1,022 |
+| 34 | `.segment_next` | string | there is a next segment | 1,022 |
+| 35 | `.heading_lev_anchor` | string | the heading has a level anchor tag | 1,854 |
+| 36 | `.segment_epub` | string | the heading opens an epub segment | 3,355 |
+| 37 | `.segment_html_is` | string | the object is inside an html segment | 47,024 |
+| 38 | `.segment_epub_is` | string | the object is inside an epub segment | 47,024 |
+| 39 | `.segment_lv4_is` | string | **and** it differs from `.segment_html_is` | 342 |
+| 40 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty | 3,319 |
+| 41 | `.lev4_subtoc` | string | once **per sub-table-of-contents entry** | 1,887 |
+| 42 | `.anchor_tag` | string | once **per anchor tag** | 7,883 |
Three of these need a word here, the first two because the model behind
them is easy to misread (see [`ocda-model.md`](ocda-model.md) sections 5