summaryrefslogtreecommitdiffhomepage
path: root/ocda-db-format-specification.md
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-29 14:02:30 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-10-03 12:09:16 -0400
commit439bb7e946e5b6e6ac350b3d4cbd3794b5b0ff21 (patch)
treed2ac6817ea529d5f5beeddbadebd053dece8b8a3 /ocda-db-format-specification.md
parentderived values, that the model left unstated (diff)
format 2.1: poem is a container of verse (objects)
.ocn_range, the first and last ocn of what a container holds, as one .ssp property and two .ocda.db columns. A poem is the one container: its verses are the citable units rather than the poem. Poem how comes before its first verse, carries ocn 0 and no identifier, and states the range, where it came after its last verse carrying that verse's ocn and identifier. So the model can now say that a non-zero ocn is unique within a document, and does, keeping the older rule for artefacts written before 2.1. A minor bump: an addition, a poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The property-count table is recounted over the regenerated reference set, the method first checked against the old set, which it reproduces. The one new endnote, a note in a poem's last verse now gathered, accounts for the other moved counts; the poems' segment names account for .segment_html_is and .segment_epub_is. (assisted by Claude-Code)
Diffstat (limited to 'ocda-db-format-specification.md')
-rw-r--r--ocda-db-format-specification.md12
1 files changed, 7 insertions, 5 deletions
diff --git a/ocda-db-format-specification.md b/ocda-db-format-specification.md
index f99868e..9f58b73 100644
--- a/ocda-db-format-specification.md
+++ b/ocda-db-format-specification.md
@@ -1,7 +1,7 @@
# The `.ocda.db` format
**The object-centric document abstraction, written as sqlite. Format
-version 2.0**, as spine 0.25.0 emits and reads it.
+version 2.1**, as spine emits and reads it after 0.25.1.
This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the text serialisation
@@ -49,7 +49,7 @@ Declared in band, in the `metadata` table:
SELECT key, value FROM metadata WHERE doc_id IS NULL;
-- build.spine_version | 0.25.0
-- schema.name | sisu-abstraction-db
--- schema.version | 2.0
+-- schema.version | 2.1
```
The rule is the model's, and identical to the `.ssp`: the minor part is
@@ -190,11 +190,12 @@ short form and the database the explicit one:
| `.part` | `is_of_part` |
| `.section` | `is_of_section` |
-Two are **expanded**, the `.ssp` folding what the database spreads:
+Three are **expanded**, the `.ssp` folding what the database spreads:
| `.ssp` property | database |
|-----------------|----------|
| `.indent: <base> <hang>` | `indent_base`, `indent_hang` |
+| `.ocn_range: <first> <last>` | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) |
| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim` |
The four **repeatable** properties become the four child tables:
@@ -210,8 +211,9 @@ And four columns come from outside the property list: `ocn`, `is_a` and
`heading_level` from the object declaration line, and `text` from its `|`
lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the
object's position within its section, and `(doc_id, section, seq)` is what
-identifies an object when `ocn` will not (see
-[`ocda-model.md`](ocda-model.md) section 3).
+identifies an object when `ocn` will not: `0`, or, before 2.1, a poem
+sharing its last verse's number (see [`ocda-model.md`](ocda-model.md)
+section 3).
### 4.1 Where the two are not symmetric