The Structured Torah API

What this is

The Torah is normally served as a linear sequence: book, chapter, verse. This API serves it as it is set in The Structured Torah — the eighty-six literary units of the Torah, each as a two-dimensional table of labelled cells, together with the markings that show how the cells answer one another.

It is one small JSON file per unit. Fetching the first unit of Genesis costs about 30 KB. There is no key to obtain, no registration and no rate limit. The licence is CC BY 4.0: use it for anything, including commercially, provided the work is credited.

This is the companion to the Structured Mishnah API, and the two are built to the same plan. A unit file here has the same field names as a chapter file there, so anything written against one dataset reads the other without changes.

It is also the text itself, not only a description of it. The Torah Units Dataset gives each unit’s verse ranges without the words, so that any translation can be laid under it. This API gives the Hebrew, cell by cell, with every verse reference located inside it.

The addresses

A book’s address component is its English name in lower case: genesis, exodus, leviticus, numbers, deuteronomy. The unit number is the one it carries within its book, so Genesis runs 1 to 19 and Deuteronomy 1 to 13.

Every file the API serves is listed on one page: all 5 book files and all 86 unit files, grouped by book.

Each unit also carries a serial_number, its place in the run of 86 across the whole Torah, which is the number the Torah Units Dataset uses. Genesis unit 1 is serial 1; Deuteronomy unit 13 is serial 86.

Finding a unit from a chapter and verse

A chapter of the Mishnah is a division the whole world already uses. A literary unit of the Torah is not: the eighty-six units are the finding this research proposes, and they do not follow the chapter breaks. So an address like /genesis/7.json is only useful to someone who already knows the division — which, at first, is nobody.

by-verse.json is the way in. Give it an ordinary reference and it tells you the unit that contains it. Its by_chapter section maps every chapter of every book to the unit or units covering it; its per-book ranges give each unit’s first and last verse, so a single verse can be placed by a simple scan.

The units run continuously from Genesis 1:1 to the end of Deuteronomy and never overlap, so every verse of the Torah lies in exactly one unit and the lookup always returns one answer. The verse counts were checked chapter by chapter against Sefaria’s: all 5,846 verses are accounted for.

One caution for anyone joining this to another edition. The two Decalogue passages, Exodus 20 and Deuteronomy 5, are divided into verses differently by different editions — a long-standing variation tied to the two cantillation traditions for the Ten Commandments. This edition gives Exodus 20 twenty-two verses where Sefaria gives twenty-three, and Deuteronomy 5 twenty-nine where Sefaria gives thirty, so a reference taken from elsewhere may sit one verse away from the same words here. It cannot send you to the wrong unit: each of those chapters lies wholly inside a single unit, so any verse of either resolves correctly under either numbering.

Finding a unit from the weekly reading

Most people find their place in the Torah by parashah rather than by chapter, so by-parashah.json maps each of the fifty-four weekly readings to the units it touches, and each unit back to the readings it falls in. Every entry says whether a unit lies wholly inside that week’s reading or continues past it, and gives the verses the two have in common.

The parashah boundaries are the standard ones, taken from Sefaria’s index. They are not a product of this research and have not been adjusted to fit it.

The two divisions are independent, and they answer different questions: the parashiyot divide the Torah for reading aloud across a year, the units divide it by literary composition. They agree more often than one might expect and disagree often enough to be worth looking at. Twenty-four of the fifty-four readings begin exactly where a unit begins. Two readings are a single unit entire — Vayetzei, and Yitro, which is Sinai and the Decalogue. Ten are built from whole units and nothing else. The remaining forty-four cut a unit somewhere. Looked at from the other side, fifty-seven of the eighty-six units sit inside a single reading, twenty-eight are split across two, and one — Genesis unit 17, Joseph Sold and Elevated — runs through three.

What a unit file contains

shape is an array of row widths, not a phrase like “3 × 2”. An irregular unit such as Genesis 13 is [[2],[1,1],[1,1],[1,1],[2]]: a five-row table whose first and last rows carry one cell spanning the full width. Reading it any other way loses the spanning cell.

The authoritative description of every field is schema.json, which is a JSON Schema and can be validated against directly.

The markers

A marker records a span of text inside a cell that is marked in the printed edition, and its type names the kind of connection. There are eight, the same eight the Mishnah uses. They are rendered as coloured words rather than as a background highlight. The definitions below are reproduced from the Color Code guide.

Markers appear in 2,262 places across the 86 unit files, in 82 of the 86 units. Each cell gives them twice: inside runs, where the cell’s text is broken into consecutive marked and unmarked spans so it can be rendered with the markings intact, and again in markers, gathered together for searching. Concatenating every run reproduces the cell’s text exactly.

The hex values above are the ones the site’s own stylesheet uses, shared with the Structured Mishnah so that the two datasets have one key between them. Where the printed Hebrew edition assigns a different value to the same marker, markers.json records it as source_edition_hex.

Reading it in Hebrew

The text is Hebrew and the tables read right to left: column 1 is the rightmost. A cell’s position gives its column number, and a renderer that places column 1 on the left will mirror the structure and reverse the argument the table is making.

Cell labels carry the same direction. A label is a row number followed by a Hebrew letter, so 2א is row 2 of the rightmost column and 2ב is row 2 of the column to its left. label_key gives the same label with a Latin letter — 2A, 2B — which is the form the Torah Units Dataset uses, so the two can be joined.

Where the data came from, and how it was checked

The data was extracted from The Structured Torah in Hebrew, the edition in which the apparatus is applied directly to the text. Every unit, cell, subdivision, verse reference and marked span in the API comes from that edition.

It was then checked against the Torah Units Dataset, which was compiled separately. Eighty-four of the eighty-six units reproduce that dataset’s recorded shape exactly, row by row, and 918 of its 938 cell and subdivision verse ranges match to the verse.

Seven points of substance remain where the two disagree — five verse ranges and two unit shapes. They are listed in discrepancies.json, with the value each source gives. Neither source has been altered to agree with the other. That file also lists nine places in the printed edition where a verse reference could not be read.

Licence and citation

CC BY 4.0. The credit line to reproduce is carried in every file, in _credit.

The companion Mishnah dataset, built to the same plan, is at /Mishnah-New/api/. The verse-range dataset, which carries the eighty-six units without their text so that any translation can be used, is at /torah-weave/data/. The method behind the tables is set out in The Woven Torah Method.