Document model
From Zacess main at 2bc7be2. Edit this page on GitHub
Every importer produces a Zacess document and every view and export reads one. It lives in
crates/zacess-core/src/model.rs. This page documents its JSON form, which is how documents are saved,
exported and passed between parts of Zacess.
A complete example is in examples/document.json. A unit test parses that
file, so the example always matches the code.
Versioning
| Rule | Detail |
|---|---|
| Current version | schema_version is 1 |
| Adding an optional field | Allowed without a new version. Older builds ignore fields they do not know |
| Renaming, removing or changing the meaning of a field | Needs a new version and an upgrade step in Document::from_json |
| Reading a newer version | Refused with an error rather than misread |
| Reading an older version | Upgraded on read and written back as the current version |
Optional fields left at their default are not written, which keeps files small. A reader must treat a missing optional field as its default.
Coordinates
Every page has a size and a unit. Every region on a page uses the same unit, measured from the
top-left corner of the page with y increasing downwards.
| Unit | Meaning |
|---|---|
pt |
PDF points, 1/72 of an inch |
px |
Image pixels |
Document
| Field | Type | Meaning |
|---|---|---|
schema_version |
integer | The version of this JSON form |
title |
string | The document title |
source |
Source | Where the document came from |
pages |
array of Page | Every page of the original, in order |
blocks |
array of Block | Every block, in reading order |
annotations |
array of Annotation | Help a helper added beside blocks. Missing when there is none |
translations |
array of Translation | Translations kept beside the original, block by block. Missing when there is none |
clip |
Clip | Where a captured clip came from. Missing for a document imported from a file |
Source
| Field | Type | Meaning |
|---|---|---|
file_name |
string | The original file name |
format |
string | One of pdf, pptx, docx, image, html and other |
Clip
Set on a document made by universal capture, so the reader can always show where it came from.
| Field | Type | Meaning |
|---|---|---|
via |
string | Which shell sent it: extension, share_sheet, clipboard or shortcut |
captured_at |
integer | When it was taken, in Unix seconds |
url |
string | The page address. Missing when there was none |
page_title |
string | The page title the shell sent. Missing when there was none |
file_name |
string | The image or file name. Missing for a page or text |
selection_only |
boolean | True when only a selection was sent. Missing when false |
A captured document has no pages. Its blocks and runs point at page 1 with an empty region.
Page
| Field | Type | Meaning |
|---|---|---|
number |
integer | Page number, counted from 1 |
width, height |
number | Page size in unit |
unit |
string | pt or px |
Origin
The link from the model back to the original. Every block has one and every imported run has one.
| Field | Type | Meaning |
|---|---|---|
page |
integer | The page number |
region |
object | x, y, width and height of the area on that page |
Block
| Field | Type | Meaning |
|---|---|---|
id |
integer | Unique within the document. Ids are never reused while a higher id exists |
type |
string | The block type, which decides the other fields |
origin |
Origin | The page and region the block came from |
type |
Extra fields |
|---|---|
heading |
level (1 to 6) and runs |
paragraph |
runs, plus optional role: body (the default), quote for a quotation or code for code whose spacing and line breaks are kept. Older builds read any role as an ordinary paragraph |
list |
ordered (true or false) and items, each with runs plus optional nested children |
table |
rows, each with cells; optional caption runs |
image |
Optional alt_text (missing means it still needs one) and optional asset, a path to the stored image |
equation |
runs as recognised, optional latex, optional mathml and display (true when set on its own line) |
page_break |
None |
A table cell has runs, plus optional header (true for a header cell), col_span and row_span
(both 1 when missing).
Run
A run is a piece of inline text.
| Field | Type | Meaning |
|---|---|---|
text |
string | The text as it now reads |
confidence |
number | How sure the recogniser was, from 0 to 1. Native text is 1 |
origin |
Origin | Where the text sits on the original page. Missing only for text the user typed |
status |
string | recognised (the default), confirmed once checked or corrected once changed |
original_text |
string | The recognised text before a correction, so the original stays one step away |
script |
string | superscript or subscript for raised or lowered text, such as an exponent or the out in V_out. Missing for ordinary text |
link |
string | The address the text links to, as written on the page. It is never fetched. Missing for text that is not a link |
Runs carry their own spacing. When two runs would join two words together, views add a single space
between them. No space is added before a run that starts with closing punctuation (., ,, ;,
:, !, ?, ), ] or }), such as the full stop after a link. No space is added after an
opening bracket ((, [ or {) either, such as the one before a link written in brackets.
Annotation
Help added beside a block by a helper, described in assist.md. It is never part of the content: the block keeps its own text and the annotation keeps a copy of it, so the original is always shown alongside.
| Field | Type | Meaning |
|---|---|---|
id |
integer | Unique within the document |
block |
integer | The block the help belongs to |
kind |
string | diagram_description or simple_explanation |
text |
string | The help itself |
original_text |
string | The block's text when the help was made |
provenance.helper |
string | The helper's name |
provenance.model |
string | The model it used, when it used one |
provenance.ran_on |
string | device or cloud |
provenance.at |
integer | When it ran, in Unix seconds |