summaryrefslogtreecommitdiffhomepage
path: root/ocda-model.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-04-18 20:28:29 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-03 12:07:15 -0400
commit0bf25dac62f2f8351367bc55ff9b373e380f7cf0 (patch)
tree6de0d5805ce835a3ceedb64afec0d609add0ad34 /ocda-model.md
sisudoc-abstraction-format 2.0: ocda-model & .ssp
In the age of maleable, replacable, improvable, text, we here continue to seek to being able to represent set text in a fixed, determinate way. this is an effort using an LLM to extract the document abstraction specifications for the program spine (Anthropic's Claude Code is used): - within the program spine the document abstraction can be captured in a .ssp document abstraction serialization file, which is a peg parsable serialisation (from which other document abstractions can be derived, such as the sqlite ocda-db abstraction) https://git.sisudoc.org/sisudoc-spine/ git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine - here in the specification: capturing, describing, stating the specification of the abstraction as captured by the .ssp document serialization, with enough detail and precision to enable the independent reading and writing of the abstraction. https://git.sisudoc.org/sisudoc-abstraction-format/ git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format - in the tools/ namespace attempts are made to successfuly, perfectly re-read and write from the abstraction using the specification alone (without use of any other prior or outside knowledge of the .ssp serialization format) sisudoc-abstraction-format is derived from the spine emitter, sisudoc/ocda/abstraction/ssp.d, whose sspObjectRecord is the single definition of what an object looks like, and checked against the document markup sample set. Should there be a difference the emitter is normative and the specification is wrong; and it states so. Three documents, so the model is described once rather than in each format specification: ocda-model.md the model: what an object is, the citation number, structure, sections, segments, digests. The part both serialisations share ssp-format-specification.md the model written as text ocda-db-format-specification.md the model written as sqlite, to come The naming follows the three levels: ocda names the model, abstraction names the pipeline stage, and .ssp and .ocda.db name the two serialisations. A thing is named for the level it belongs to, which is why this file is ssp-format-specification.md and not ocda-format-specification.md: it specifies one serialisation, not the model. The specification states the version and the policy that governs it, and separates conformance into what a reader must do, should do, and what a writer must do. The single "should" is that a reader should report what it ignored: without it, silence cannot be told from understanding. Both worked examples regenerated from spine 0.25.0. The excerpt carries one complete object embedding an image, so the .image record and the image marker in the object text can be read against each other. The name .ssp is recorded: it belongs to the .sst, .ssm, .ssi family and stands loosely for sisu peg or sisu parsable, .ssa for sisu abstraction having been thought taken by other projects. Add a top-level README.md identifying the repository as a specification (not a program), summarising what .ssp is (a human-readable, PEG-parsable serialisation of spine's in-memory document abstraction), listing the line-type grammar at a glance, and pointing readers at format-specification.md for the full reference and at the two example .ssp files shipped alongside. Canonical URLs use the new git.sisudoc.org/tools/ namespace, matching the parallel moves in tree-sitter-sisu and ssp-reader and the local rename of sisudoc-spine-utils/ to sisudoc-spine-tools/. Cross-references to ssp-reader and tree-sitter-sisu follow the same convention. (assisted by Claude-Code)
Diffstat (limited to 'ocda-model.md')
-rw-r--r--ocda-model.md143
1 files changed, 143 insertions, 0 deletions
diff --git a/ocda-model.md b/ocda-model.md
new file mode 100644
index 0000000..b97cf09
--- /dev/null
+++ b/ocda-model.md
@@ -0,0 +1,143 @@
+# The object-centric document abstraction (OCDA)
+
+**The model.** What a document *is* once spine has parsed it, independent
+of any file it is written to.
+
+Two serialisations carry this model, and they carry **one version number
+between them**, because neither may express what the other cannot:
+
+| | |
+|---|---|
+| [`ssp-format-specification.md`](ssp-format-specification.md) | the OCDA as text, `.ssp` |
+| `ocda-db-format-specification.md` | the OCDA as sqlite, `.ocda.db` *(to come)* |
+
+This document is what they share. It describes objects; they describe
+writing objects down.
+
+## 1. Three words, three levels
+
+The terms are used precisely in this repository and in spine, and the
+distinction is worth holding:
+
+| level | term | names |
+|-------|------|-------|
+| the model | **OCDA** | what a document is once parsed: numbered objects with structure, identity and digests. Independent of any file, any stage, any tool |
+| the stage | **abstraction** | the middle of spine's **markup -> abstraction -> output**: the act of building the model, and the point at which a document may now enter the pipeline |
+| the serialisations | **`.ssp`**, **`.ocda.db`** | the model written down, as text and as sqlite |
+
+A thing is named for the level it belongs to. Something true of the model
+whatever file it is in takes *ocda*; something about the pipeline stage
+takes *abstraction*; something that reads or writes one file form takes
+that form's name.
+
+## 2. The object
+
+A document is a sequence of **objects**, grouped into sections. An object
+is a paragraph, a heading, a table, an endnote, a line of verse: the unit
+the document is made of and the unit it is cited by.
+
+Every object carries:
+
+- an **object citation number** (OCN), section 3;
+- a **kind**, one of sixteen: `para`, `heading`, `toc`, `bookindex`,
+ `endnote`, `code`, `bibliography`, `comment`, `verse`, `glossary`,
+ `quote`, `poem`, `block`, `table`, `blurb`, `group`;
+- its **place in the structure**: parent, ancestors, and for a heading its
+ children and its last descendant;
+- its **text**, in spine's internal representation;
+- a **digest** of that text.
+
+## 3. The object citation number
+
+The OCN is the heart of the model and the reason for it.
+
+**An object's OCN is the same in every format spine writes.** A paragraph
+that is object 42 in the HTML is object 42 in the EPUB, in the PDF, in the
+plain text, in the search database and in both serialisations of the
+abstraction. A citation to object 42 of a document is therefore a citation
+to a fixed piece of text, not to a page in one edition or a scroll position
+in one rendering.
+
+Three properties follow, and each is a trap for a reader that assumes
+otherwise:
+
+- **Not every object has one.** Generated furniture, and objects the markup
+ has suppressed, carry `0`. There are many of them: 7,543 across the 36
+ document reference collection.
+- **`0` is therefore not an identity.** Objects sharing `0` are not the
+ same object, and `0` must never be used as a key.
+- **An OCN is not unique within a document even when non-zero.** A poem and
+ its verses share one; `through_the_looking_glass` has 21 such cases. Key
+ on position within a section when one row is wanted.
+
+## 4. Structure
+
+Structure is carried by number, not by nesting: an object names its parent
+rather than containing its children. This is what lets the serialisations
+be flat and the model be walked in either direction.
+
+- **`parent`** - the OCN of the object this one hangs from.
+ **A parent of `0` is not "no parent"**: it is a parent heading the author
+ has made non-substantive, its OCN suppressed or a dummy heading
+ introduced to segment an output. The distinction is preserved
+ deliberately, and a reader walking upward must stop at `0` rather than
+ treat it as missing, or the walk will not terminate.
+- **`ancestors`** - eight slots, the OCN at each level above this object,
+ so the path to the root is available without walking.
+- **`ancestors_collapsed`** - the same with the empty levels removed.
+- **`children`** - a heading's child headings.
+- **`last_descendant`** - the last OCN under a heading, which makes a
+ subtree a **range** rather than a traversal: everything from the
+ heading's OCN to its last descendant is inside it.
+
+## 5. Sections
+
+Objects are grouped into nine sections, in this order:
+
+```
+head toc body endnotes glossary bibliography bookindex blurb tail
+```
+
+`head` is the document's title matter, `body` the document proper, and the
+rest are generated or gathered. `tail` is the end of document some output
+writers use. A section with no objects is not carried.
+
+## 6. Segments
+
+An output may be one file or many. A **segment** is one of the many: a
+chapter-sized piece of HTML or EPUB with its own name and its own
+navigation.
+
+Two different questions are asked about segments, and the model answers
+both separately because the answers differ:
+
+- **which segment does this heading open?** Set on headings only.
+- **which segment is this object in?** Set on nearly every object.
+
+Without the second, a reader cannot say where a paragraph belongs. The
+search database reads the second.
+
+## 7. Digests
+
+The model is checkable at four levels, and the chain is what lets an
+artefact be verified rather than trusted:
+
+```
+the markup files ──> a digest over every markup file of that language
+the serialisation ──> a digest of the .ssp a database was built from
+each object ──> a digest of the object's text
+each image ──> a digest of the image file, with its size in bytes and pixels
+```
+
+An object's digest is over its text alone, so a change to one paragraph
+moves one digest and no other.
+
+## 8. What the model does not hold
+
+- **The markup.** The model is what the markup produced, not the markup
+ itself. An artefact that carries both is the `.ocda.db`, which carries
+ the markup alongside the model rather than within it.
+- **The images.** The model *names* them, with digest, byte size and pixel
+ size, and they must be found beside the file for a document to be
+ complete.
+- **Any output format.** No HTML, no page numbers, no typesetting.