This document describes the JSON format used in MAM-simple and how to extract text from it.
| folder | versification |
|---|---|
json-vtrad-bhs |
BHS |
json-vtrad-sef |
Sefaria |
json-vtrad-mam |
MAM native |
Each file is named for one book24 (e.g., 1Sam-2Sam.json, Gen.json, Hos-Mal.json).
A book24 corresponds to one of the 24 books of the Hebrew Bible; some of them span more than one book39, i.e. some of them span more than one book in the system that divides the Hebrew Bible up into 39 rather than 24 books.
The json-vtrad-mam folder holds all 24 book-group files. The BHS folder holds six groups — 1Sam-2Sam, Deut, Exod, Jer, Josh, and Num — and the Sefaria folder holds the same five groups except Num. The other groups use the MAM file.
To read book group X in versification V, read json-vtrad-<V>/, falling back to json-vtrad-mam/. In Python:
from pathlib import Path
def book_group_path(vtrad: str, stem: str) -> Path:
"""The JSON file for one book group in mam, bhs or sef versification."""
if vtrad not in {"mam", "bhs", "sef"}:
raise ValueError(f"Unknown versification {vtrad!r}")
asked = Path(f"json-vtrad-{vtrad}") / (stem + ".json")
if asked.is_file():
return asked
base = Path("json-vtrad-mam") / (stem + ".json")
if not base.is_file():
raise FileNotFoundError(base)
return base
Every cv-label and every byte of text in the file the fallback returns is what
versification V calls for, which is exactly why it is not stored twice. And the file
says so itself: its root's versification-tradition holds a comma-separated set naming
every tradition it is correct for, so a Ruth read this way says
"versification-tradition": "vtmam,vtbhs,vtsef" and a Num says
"versification-tradition": "vtmam,vtsef". A reader can therefore check the file it landed
on rather than trust the fallback rule — see
the JSON guide's root object.
For a full description of where and how the three versifications differ, see Versification Differences.
MAM-simple is an extract of MAM, not a complete representation of the
MAM-parsed source. Every JSON file embeds a consumer_notice immediately after its
provenance field. The notice points back to this section.
The following rules protect distinctions that a generic tree walk would erase:
cant-all-three; do not
concatenate alternatives, a scrdfftar target with its note, or a
good-ending repetition with running text. MAM-simple has already
resolved or removed some choices retained by MAM-parsed, so absence here does not
establish absence in MAM-parsed.kq element is not a choice that must be resolved: an edition may show its
ketiv and its qere together, separated by a space and kept distinguishable, as an unpointed
ketiv beside its pointed qere is, or only one of them. Identify the two children of
kq by element type, not by position. They are in the order that MAM's rendered
pages on Hebrew Wikisource have, which is qere first in about one pair in eight.slh-word spell one atom-form. Its slhw-desc-0 attribute repeats
the uninterrupted atom-form without the letter formatting; the attribute is not
additional Scripture.lp-legarmeih
node represents a mark that belongs with the preceding atom. Narrow-sense paseq
(lp-paseq) is not part of the preceding atom.lp-paseq) forms no compound of any kind; only maqaf joins atoms
into a chanted word. MAM encodes no whitespace before or after narpas to avoid
prescribing display spacing, not to group the surrounding text. An edition decides
whether to display spacing before and/or after narpas; an analytical consumer need
not make a display-spacing decision.spi-invnun stands for the inverted nun,
followed by a space when its class is including-trailing-space, and a
plain-text projection must supply the nun and any such space rather than nothing. Within a
verse, shirah-space and the parashah markers spi-samekh2,
spi-samekh3, spi-pe2 and spi-pe3 can be the only separator
between adjacent text, with no literal whitespace on either side, as at 1Chr.11.26 and
1Chr.16.8. Dropping such a separator fuses separate atoms, so a plain-text projection must
supply one; a layout-preserving renderer implements the documented space or break. MAM's gray
maqaf (implicit-maqaf) also has no text, and no whitespace stands on either side of
it. A consumer may read it as a maqaf, as a space or as a distinct kind of maqaf, such as a gray
one; a consumer that drops it runs the atoms on either side of it together into one atom, which
is very unlikely to be what it wants.starts-with-sampe
and ends-with-sampe fields describe one break. Do not count the same break three
times.Nothing beyond the standard library is needed. Run from the MAM-simple directory, this
program writes the plain text of Job 34 to py-examples-out/. It handles only
the elements Job 34 has, and raises on any other rather than guess:
import json
from pathlib import Path
PASEQ = "\N{HEBREW PUNCTUATION PASEQ}"
MAQAF = "\N{HEBREW PUNCTUATION MAQAF}"
# This chapter has only these text and punctuation roles.
_CONTRIBUTION = {"lp-legarmeih": PASEQ, "implicit-maqaf": MAQAF}
def verse_text(verse):
"""The plain text of one verse of Job 34."""
if "text" in verse:
if "contents" in verse:
raise ValueError("text and contents cannot co-occur")
return verse["text"]
parts = []
for node in verse.get("contents", []):
kind = node["type"]
if kind == "text":
if set(node) != {"type", "text"}:
raise ValueError(f"Unexpected text node {node}")
parts.append(node["text"])
elif kind in _CONTRIBUTION:
if set(node) != {"type"}:
raise ValueError(f"Unexpected punctuation node {node}")
parts.append(_CONTRIBUTION[kind])
else:
raise ValueError(f"{verse['osisID']}: unhandled {kind}")
return "".join(parts)
def main():
with open("json-vtrad-mam/Job.json", encoding="utf-8") as source:
root = json.load(source)
book = next(n for n in root["contents"] if n["type"] == "book39" and n["osisID"] == "Job")
chapter = next(n for n in book["contents"] if n["type"] == "chapter" and n["osisID"] == "Job.34")
Path("py-examples-out").mkdir(exist_ok=True)
with open("py-examples-out/job-34.txt", "w", encoding="utf-8", newline="\n") as out:
for verse in chapter["contents"]:
if verse["type"] != "verse":
raise ValueError(f"Job.34: unhandled {verse['type']}")
out.write(f"{verse['osisID']}: {verse_text(verse)}\n")
if __name__ == "__main__":
main()
Two points in it are easy to get wrong:
lp-legarmeih contributes the glyph U+05C0, and implicit-maqaf contributes an ordinary maqaf. MAM
encodes no space around implicit-maqaf, so a program that gives it nothing runs
two atoms together: Job 34:10 would read שִׁמְע֫וּלִ֥י instead of שִׁמְע֫וּ־לִ֥י.UnicodeEncodeError. If you do want it on stdout, call
sys.stdout.reconfigure(encoding="utf-8") first.To read another chapter, add a branch for each element the program raises on; Extracting the plain text of a verse says which elements need recursion and which hold alternatives to choose among.
py-examples/ Program, and the Two That Were RetiredThe py-examples/ directory contains one complete working example:
main_letter_small_job_example.py — reports all of the letter-small elements in Job.json, writing output to py-examples-out/letter-small-job.txt .It inventories small-letter objects in JSON, including ketiv and qere branches and notes.
Two further examples, main_mam4sef_example.py and main_mam_osis_example.py, were
retired on 2026-09-12. They created the Sefaria and OSIS editions of MAM from this
product — the first from the JSON format, the second from the XML format — and they were
written when MAM-simple, MAM-for-Sefaria and MAM-OSIS were separate repositories. Both editions
are still produced by MAM-basics' py/ and py/. Both generators now read JSON and
follow the incremental-folder rule above: read the requested versification file when present and
the MAM file otherwise.
The Sefaria and OSIS generators both use a recursive handler pattern, in which each element type has a registered handler function. It remains the fullest worked answer to "how do I process the full range of MAM-simple element types", so it is described here, and the modules named are in MAM-basics rather than in this product.
For the Sefaria generator the relevant modules are:
py/mb_sefaria/mam4sef_or_ajf.py — reads JSON, walks the tree with _handle()py/mb_sefaria/mam4sef_handlers.py — handler functions for every element type, keyed by (tag, class) tupleThe OSIS generator uses the same pattern over JSON objects, with handler
functions in py/ and the walk itself in
py/. Its _handle() is where to look to see the pattern
whole. It processes one element by first processing that element's children, and then
calling the element's handler with three arguments:
etel — the JSON object itselfofc1 — output for all children, summed togetherofc2 — output for all children, per childWhen the element has a text field, ofc1 is that field instead, which works
because a text field and a contents array never co-occur. Handlers are keyed by
(tag, class), so ("kq", "sep-maqaf") gets a different handler from ("kq", None).
The ofc2 argument is what lets a handler choose among its children rather than take
them all: scrdfftar's handler uses it to tell the target from the note.
Together, MAM-basics' Sefaria and OSIS generators are the canonical reference for how to process the full range of MAM-simple element types.