Reading MAM-simple

This document describes the JSON format used in MAM-simple and how to extract text from it.

File Layout

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 BHS and Sefaria folders are incremental, with the MAM ones as the base

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>/X.json, falling back to json-vtrad-mam/X.json. 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.

Consumer notice

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:

Format Details

Reading MAM-simple from Python

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/job-34.txt. 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:

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.

The py-examples/ Program, and the Two That Were Retired

The py-examples/ directory contains one complete working example:

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/main_mam4sef.py and py/main_mam_osis.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 Recursive Handler Pattern

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:

The OSIS generator uses the same pattern over JSON objects, with handler functions in py/osis/osis_handlers.py and the walk itself in py/osis/osis_runner.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:

When 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.