diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-25 22:28:50 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-03 21:50:59 -0400 |
| commit | 5a5036e53aa18afa61d6e475336cd96c115dac00 (patch) | |
| tree | 669a9190703b6833591311c73f4646a123c11dc3 /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.md | 97 |
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 |
