# sisudoc-abstraction-format Specification of the **object-centric document abstraction** that [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) builds from SiSU markup, and of the two forms it is written in: **`.ssp`**, text and PEG-parsable, and **`.ocda.db`**, sqlite. The two carry one version number between them, because neither may express what the other cannot. ## What this is A specification, not a program. The repository ships: - [`ocda-model.md`](ocda-model.md) - **the model**: what an object is, the citation number, structure, sections, segments, digests. The part both serialisations share, and the place the three terms *ocda*, *abstraction* and `.ssp` are told apart. - [`ssp-format-specification.md`](ssp-format-specification.md) - **the `.ssp`**: the model written as text. - [`ocda-db-format-specification.md`](ocda-db-format-specification.md) - **the `.ocda.db`**: the model written as sqlite. - [`example-autonomous-contract.ssp`](example-autonomous-contract.ssp) - spine's output for that sample document, complete and unedited. - [`example-wealth-of-networks.ssp`](example-wealth-of-networks.ssp) - an excerpt of spine's output for that sample document: verbatim lines, marked elisions, keeping the preamble, the `@head` section and a run of body objects that includes an object embedding an image. The whole file runs to 27,769 lines. Both carry, in their opening comment lines, the command that regenerates them, so they can be diffed against a run rather than taken on trust. Both are output of **spine, format 2.1** (neither holds a poem, so from 2.0 to 2.1 each changed by its version line alone). ## Version The format is at **2.1**, and says so on the first line of every file: ``` % SiSU Document Abstraction v2.1 ``` The minor part is raised when a property is added, the major part when one changes meaning or goes away, and a reader checks the major part and refuses what it does not know. The history is in the specification. ## What is `.ssp`? Spine's processing pipeline goes **markup -> abstraction -> output**. The abstraction stage builds an in-memory object model: every paragraph, heading, table, footnote etc. is a numbered object with parent / sibling / type metadata ("OCN" - Object Citation Numbering). `.ssp` is a faithful text serialisation of that object model. It is designed for: - Inspecting and debugging spine's abstraction stage. - Diff-friendly version control of document structure (a `.ssp` diff between two markup edits shows exactly which objects changed). - Round-trip experiments: markup -> spine -> `.ssp` -> alternative renderers (HTML, LLM-ready chunks, ...) without rerunning spine. - A stable contract between spine and downstream consumers that do not want to link against spine's internal D types. Line types (full grammar in [`ssp-format-specification.md`](ssp-format-specification.md)): ``` @name { section / block open } section / block close [N] type ... object declaration (N = OCN, 0 if unnumbered) .name: value property of the preceding object | text content text line of the preceding object blank line (object separator) % comment comment (ignored by parser) ``` ## Audience - Developers writing readers / converters for spine's abstraction (readers written from this specification alone: sisudoc-ssp-reader, sisudoc-ocda-db-reader, now frozen with current readers offered and maintained within sisudoc-ocda-lib). - Anyone studying spine's internal document model without reading the D source. - LLM / search / indexing tooling that consumes structured document data downstream of spine. End-user document authors do not need to read this; they write `.sst` / `.ssm` markup, which spine then turns into `.ssp` along the way to the final output formats. ## Quickstart Read the spec: ```sh $EDITOR ssp-format-specification.md ``` Look at a real example: ```sh $EDITOR example-wealth-of-networks.ssp ``` Generate your own `.ssp` from a sample document via spine: ```sh # inside sisudoc-spine/ result/bin/spine --source --pod2 --output=/tmp/ssp path/to/pod ls /tmp/ssp/pod/*/media/abstraction/*.ssp ``` `--pod2` writes the abstraction as `.ssp` and bundles it into the source pod. (See sisudoc-spine's CLI help for the current flags.) ## License AGPL-3.0-or-later, matching the parent [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) project. ## Repository - **Canonical URL:** https://git.sisudoc.org/sisudoc-abstraction-format - **Clone:** `git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format` ## Related projects - [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) - the document engine that writes `.ssp` and `.ocda.db` files. - [sisudoc-ocda-lib](https://git.sisudoc.org/sisudoc-ocda-lib) - the abstraction read as a library, from a .ssp, a .ocda.db or a .sisupod (D and Gleam). To be published. - [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) - sample writers over that library (text, markdown, html, epub, typst), each checked against spine. To be published. - [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar for the .sst / .ssm markup spine reads before writing a .ssp.