What the Document Says It Is Made Of

Summary

Ink on a page has no order of its own. A person sees that the big words at the top are a heading and that the two columns are read one after the other, but a program sees only marks placed at coordinates, in whatever order they were drawn. Once it is written down, a document can be read aloud correctly, copied without scrambling, and reflowed on a small screen. You can also say a passage is in another language, so it is pronounced properly, and give a picture a sentence describing it for somebody who cannot see it.

Request Schema

• structure — object, optional. Absent, the file says nothing about itself.
• structure.lang — string, optional, a BCP 47 tag. The tongue the document's words are written in.
• structure.roles — array, optional. Tags of the request's own, each an object of tag and standard, the standard tag it is read as.
• structure.children — array, optional. The elements at the head of the tree, in reading order.
• A node names either branch, the name of a branch built elsewhere, and nothing else at all; or tag, the standard's name for what it is (Document, Sect, H1, P, Figure), and then children, other nodes, or content, the label of the marked content an item left behind, one of the two and never both. A node naming neither a tag nor a branch is refused.
• A node also takes namespace, lang for a passage in another tongue, alt, a sentence describing what cannot be seen, and actual_text, what a passage really says when its ink does not spell it.
• A node also takes expansion, the words an abbreviation or an acronym stands for, written out, which reading software says in place of the letters.
• A node also takes list_numbering on the node of a list, one of none, unordered, description, disc, circle, square, ordered, decimal, upper_roman, lower_roman, upper_alpha and lower_alpha. A list inside one that states a scheme and states none of its own is numbered the way the outer one is.
• A node also takes placement, where the element stands in the flow of its page, one of block, inline, before, start and end. Absent, the element is a block or sits inside its line, as its tag is. Nothing on the page moves for it: it tells software reflowing the document where to put the element back.
• structure.namespace_roles — array, optional. Tags of one namespace read as tags of another, each an object of namespace, tag, standard and target_namespace: the tag of namespace is read as standard of target_namespace. It is what lets two namespaces use one name for different things. PDF 2.0.
• structure.pronunciation_lexicons — array of strings, optional. The name of files among attachments, each a pronunciation lexicon in the W3C format, that reading software says the document's words with, the first match winning. A name no attachment declares is refused.
• A node also takes aria_role, what the element is for where the standard's tags have no word for it, as a role of WAI-ARIA 1.1 or of its Digital Publishing module, spelt as the vocabulary spells it: doc-bibliography, doc-noteref, "alertdialog". "none" is read as "presentation". A word the vocabulary does not hold, or one of its abstract roles, is refused.
• A node also takes phoneme, how its content is said, spelt in a phonetic alphabet, and phonetic_alphabet, that alphabet, which the nodes nested in it take when they state none: ipa, x_sampa, pinyin, wade_giles, or {"other": name} for one the standard does not name. Absent, reading software takes the IPA.
• A node of a list also takes continues_list, the earlier list it carries on from: "preceding", the list before it in the tree, or {"from": id}, the list whose id is given. An id no node carries is refused.
• A "Form" node enclosing a printed form field also takes print_field, an object of role (radio_button, check_box, push_button, text_value or list_box), checked (on, off or neutral) and description, the field's alternate name, each written only where it is stated.
• An "Artifact" node also takes artifact, what the furniture it encloses is: an object of kind (pagination, layout, page or inline), subtype, spelt as the file holds it (Header, Footer, Watermark, PageNum, Bates, LineNum, Redaction, or a name of one's own under ISO 32000-2 Annex E such as ACME_Stamp), and bbox, the box it covers, four edges in the page's points, each written only where it is stated. Any other subtype is refused.
• A node also takes refers_to, the id of the nodes it refers to — a note to what it annotates, a caption to what it captions. An id no node carries is refused.
• A node also takes attributes, the attribute objects it states: what its appearance means, such as the box a figure covers, the alignment of a cell or the thickness of a border. Each is an object of owner, the standard's name for the family it belongs to (Layout, List, PrintField, Table, UserProperties) or a name of one's own, or else namespace, the address of a vocabulary of one's own, in PDF 2.0; entries, each value under its name; and revision, optional, the revision of the element it is tied to. A value is true or false, a number, a string, an array of values, {"name": "Center"} for a name, or {"dictionary": {…}} for values grouped under names. An object stating both owner and namespace, or neither, is refused.
• structure.class_map — array, optional. Attribute objects filed once under a name, each class an object of name and attributes, written as a node writes them. A node also takes classes, the classes it belongs to, each an object of name and revision, optional, and holds their attribute objects as its own.
• A cell of a table stated node by node, a "TH" or a "TD", also takes scope (row, column or both, on a "TH"), col_span and row_span, the columns and rows it covers counting its own, and headers, the id of the header cells it sits under.
• A node holding children or content also takes annotations, the mark a link item or a form field carries, so the element holds that link or that field and the link leads back to it: what a document claiming pdfua1 or pdfua2 owes every link and every field. A radio group files one entry per button under its mark.
• A node also takes imported_runs, the runs of a page brought in by a pdf_page item: {"page": label, "runs": [0, 1]}, the own_runs label of that item and the numbers its own document gave the runs. annotations and imported_runs are refused on a node whose content names several runs.
• An item that draws, where no element of the tree owns its run, takes described, what the run says for itself: an object of expansion, actual_text, alt and lang, at least one stated. It is refused beside tag or artifact, and inside a named drawing.

Scope: the whole document. It is what accessible is judged against; on its own it costs nothing and is simply read by whoever wants the order and the meaning rather than the coordinates.