MAM-simple is distributed in JSON. Each book-group file holds a root object, book39 objects, chapters, verses, and the typed child objects described here.
{
"provenance": "This file was generated by MAM-basics/py/main_mam_simple.py.",
"consumer_notice": {
"summary": "...",
"critical_rules": ["...", "..."],
"documentation": "https://bdenckla.github.io/MAM-basics/MAM-simple/reading-mam-simple.html#consumer-notice"
},
"versification-tradition": "vtmam,vtbhs,vtsef",
"contents": [ "...", "...", "..." ]
}
The root object has exactly these four fields, in this order. provenance identifies
the generator. consumer_notice is the warning label described in the
consumer notice; its actual summary and rule
strings are not abbreviated in the generated files.
The versification-tradition field is a string holding a comma-separated set: every
versification tradition whose cv-labels this file carries, drawn from vtmam, vtbhs
and vtsef, in that order. The contents array contains book39 objects and parashah-marker objects.
(Throughout this section, ["...", "...", "..."] is used to express "one or more elements" while still being valid JSON.)
Its value is a comma-separated set: every versification tradition whose cv-labels this
file carries, drawn from vtmam, vtbhs and vtsef, in that order.
Most often that is more than one, because the three traditions place the same cv-labels
in most of the Bible, and the file is then correct for each of them.
An json-vtrad-bhs or json-vtrad-sef file always names its own tradition and nothing
else, those folders holding only the book groups where that tradition parts company with
MAM.
An json-vtrad-mam file names every tradition that agrees with MAM for that book group:
| Value | Book groups | Meaning |
|---|---|---|
vtmam,vtbhs,vtsef |
18 of 24 | all three traditions agree here |
vtmam,vtsef |
Num |
Sefaria agrees with MAM; BHS does not, and has its own file |
vtmam |
1Sam-2Sam, Deut, Exod, Jer, Josh |
both other traditions differ, and both have their own files |
So a reader that fell back to an json-vtrad-mam file, because the folder it asked for
did not hold that book group, can confirm from the file itself that the file is right for
the versification it wanted.
The value was a single tradition until 2026-09-12, naming the folder the file came from. Every value written before that date is still true under the reading above, a single value being a one-element set.
{
"type": "book39",
"osisID": "Ruth",
"contents": [ "...", "...", "..." ]
}
The contents array contains chapter objects and parashah-marker objects.
{
"type": "chapter",
"osisID": "Ruth.1",
"contents": [ "...", "...", "..." ]
}
The contents array contains verse objects and parashah-marker objects.
Simple verses (no special markup) have a text field directly:
{
"type": "verse",
"osisID": "Ruth.1.1",
"text": "וַיְהִ֗י בִּימֵי֙ ..."
}
Complex verses (with legarmeih, ketiv/qere, etc.) have a contents array instead:
{
"type": "verse",
"osisID": "Ruth.1.2",
"contents": [
{ "type": "text", "text": "וְשֵׁ֣ם הָאִ֣ישׁ ..." },
{ "type": "lp-legarmeih" },
{ "type": "text", "text": " מַחְל֤וֹן ..." }
]
}
{ "type": "spi-pe2" }
Parashah-marker objects can appear:
contents array, between book39 objects (e.g., between 1 Samuel and 2 Samuel)book39 contents array, between chapterschapter contents array, between versesverse contents array, within a verseThis treatment of parashah breaks is a distinctive feature of MAM-simple. Most encodings of the Tanakh make every parashah break belong to a verse. This requires the vast majority of breaks to be assigned to either the preceding or following verse. (The few mid-verse breaks of course naturally belong to their verse.)
For a break between verses, including at chapter and book boundaries, MAM-simple stores
a parashah-marker object outside the verse objects. The adjacent verses'
starts-with-sampe and ends-with-sampe fields record the same break.
These fields support consumers that need breaks assigned to verse beginnings or endings.
A break within verse text has its marker object inside the verse, without corresponding
start/end fields.
This makes MAM-simple less simple, but we believe the tradeoff is a good one.
Choosing a single encoding would simplify the data at a cost to use-cases that don't fit
that encoding well.
A ketiv/qere pair is a kq object whose contents holds a kq-k object (the ketiv) and a
kq-q object (the qere), in the order that MAM's rendered pages on Hebrew Wikisource have.
Those pages usually have the ketiv first, but they have the qere first in about one pair in
eight, as at Lam.1.18:
{
"type": "kq",
"contents": [
{ "type": "kq-q", "text": "הָֽעַמִּ֗ים" },
{ "type": "kq-k", "text": "עמים" }
]
}
Identify the two by type, never by position; see
Ketiv/qere details.
A silluq-before-meteg object represents an atom with a silluq before a meteg.
The object has type, text, and letters-with-silluq, without contents.
text is the full marked atom. letters-with-silluq contains the same Hebrew letters and exactly one U+05BD identifying silluq, with no other marks or punctuation. The full atom has the identified mark and at least one later U+05BD. Both fields exclude sof pasuq. A reader must not assume that the last U+05BD is silluq.
For example, this part of a verse’s contents keeps sof pasuq outside the annotation:
[
{
"type": "silluq-before-meteg",
"letters-with-silluq": "לכלֽהנה",
"text": "לְכֻלָּֽהְנָֽה"
},
{
"type": "text",
"text": "׃"
}
]
Generic text consumers take only text; they never append letters-with-silluq
as running text. The two current cases are 1 Kings 7:37 and Job 4:12.
The lp-legarmeih type identifies legarmeh, which is part of the cantillation system.
The lp-paseq type identifies paseq in the narrow sense, which is not part of the cantillation system,
or is, at most, at the periphery of the cantillation system.
An edition or other application may use or discard this distinction.
MAM encodes no whitespace before or after lp-paseq. That omission does not
group the surrounding text. Narpas (narrow-sense paseq, lp-paseq)
forms no compound of any kind; only maqaf joins atoms into a chanted word. Nor does the
omission prescribe how the glyph should be spaced in an edition: an edition decides
whether to display spacing before and/or after narpas, while an analytical consumer need
not make a display-spacing decision.
Stored running text is in a text field. Description fields such as slhw-desc-0 and letters-with-silluq are metadata or alternative representations; do not append them to running text. Punctuation objects can contribute a character without storing it in a text field.
An object never has both a text field and a contents array.
Some object types have neither. Where text is stored, it is either in the object's
text field or assembled from its selected children.
The combining marks of a letter are in MAM's order, not Unicode's. Five code points have priority: shin dot (U+05C1), sin dot (U+05C2), dagesh/mapiq/shuruq dot (U+05BC), dagesh ḥazaq (U+05C9), and rafe (U+05BF). The two dagesh code points have the same priority and retain their relative order. Every other mark keeps its relative order. The consequence you will meet first is that a dagesh comes before its vowel, where Unicode's canonical order puts the vowel first.
This text is therefore neither NFC nor NFD. A literal search using Unicode-normalized input can miss equivalent-looking MAM text, and normalization can change bytes without changing the display. Preserve MAM order when a byte-for-byte round trip or MAM-compatible output is required. A consumer whose output contract requires another order can transform deliberately, but should transform both sides before comparison rather than assume rendered equality means byte equality.
MAM's mark order is a property of MAM itself, which MAM-simple preserves rather than
imposes: the generator checks every object it renders and aborts on a violation
instead of repairing one.
The implementation is give_std_mark_order, in MAM-basics'
py/.
The existing combining-class values are attributed to the SBL Hebrew Font recommendation;
the repository assigns U+05C9 the same priority as U+05BC.
Only those five code points have a declared priority. A vowel and an accent pass in either order, so MAM's mark order is not a full canonical form: agreement on those priorities does not imply byte-identity after a round trip through some other sort.
text fieldA verse object without any special features stores its full, plain text in a text field, e.g.:
{
"type": "verse",
"osisID": "Job.34.2",
"text": "שִׁמְע֣וּ חֲכָמִ֣ים מִלָּ֑י וְ֝יֹדְעִ֗ים הַאֲזִ֥ינוּ לִֽי׃"
}
Most verses are of this kind. A verse with no content may have neither text nor contents.
A verse object with one or more special features
(legarmeh, paseq, ketiv/qere, etc.)
has no text field.
Instead, the plain text between special features is in text child objects,
interspersed with objects encoding special features, e.g.:
{
"type": "verse",
"osisID": "Job.1.1",
"contents": [
{
"type": "text",
"text": "אִ֛ישׁ הָיָ֥ה בְאֶֽרֶץ־ע֖וּץ אִיּ֣וֹב שְׁמ֑וֹ וְהָיָ֣ה"
},
{
"type": "lp-legarmeih"
},
{
"type": "text",
"text": " הָאִ֣ישׁ הַה֗וּא תָּ֧ם וְיָשָׁ֛ר וִירֵ֥א אֱלֹהִ֖ים וְסָ֥ר מֵרָֽע׃"
}
]
}
verse has a text field, that field is the whole plain text.text field or, if it has children instead, the text assembled from those. A child
with neither can still contribute, as the
consumer notice and
Reading MAM-simple from Python
explain.Step 2 has to recurse, and a reader that skips the recursion loses text silently.
It is tempting to write step 2 as "concatenate the text fields of the text
children," but plain text also sits below kq, kq-trivial, slh-word,
cant-all-three, scrdfftar and the ketiv/qere singletons. A direct-children-only
walk drops every ketiv/qere and every suspended-letter word without raising anything.
Raise on an unrecognized type rather than ignoring it, so that a type added later
announces itself.
Four object types hold alternatives rather than a stretch of running text, and for these a reader has to choose among the children instead of concatenating them:
| Element | The choice |
|---|---|
kq |
kq-k (ketiv, unpointed) or kq-q (qere, pointed), in either order |
cant-all-three |
cant-combined, cant-alef, or cant-bet |
scrdfftar |
sdt-target is the text; sdt-note is a note about it |
good-ending |
an added repetition, not part of the running text |
The "Text" column says where an object's text is: text means the text field,
contents means it always has a child array instead, and either means both cases occur.
| Element | Meaning | Text |
|---|---|---|
text |
A run of Hebrew text | text |
silluq-before-meteg |
An atom with a silluq before a meteg | text |
lp-legarmeih |
Legarmeh | none |
lp-paseq |
Paseq in the narrow sense | none |
implicit-maqaf |
Maqaf that is implicit in the manuscript | none |
slh-word |
An atom with a small, large, or hung letter | contents |
letter-small |
Small letter | text |
letter-large |
Large letter | text |
letter-hung |
Hung (aka suspended) letter | text |
kq |
Ketiv/Qere pair | contents |
kq-k |
Ketiv portion | either |
kq-q |
Qere portion | either |
kq-trivial |
Trivial Ketiv/Qere | either |
kq-k-velo-q |
Ketiv with no Qere | text |
kq-k-velo-q-maq |
Maqaf after a ketiv with no qere | none |
kq-q-velo-k |
Qere with no Ketiv | text |
cant-all-three |
Wraps combined, alef, and bet | contents |
cant-combined |
Combined representation | either |
cant-alef |
Alef strand | either |
cant-bet |
Bet strand | either |
shirah-space |
Shirah (song) spacing | none |
good-ending |
Repeated ending | text |
scrdfftar |
Targeted scroll-difference note | contents |
sdt-target |
The scrdfftar target |
either |
sdt-note |
The scrdfftar note itself |
either |
spi-samekh2, spi-samekh3 |
Parashah setumah markers | none |
spi-pe2, spi-pe3 |
Parashah petuḥah markers | none |
spi-invnun |
Inverted nun | none |
letter-small, letter-large and letter-hung appear only inside slh-word.
Element boundaries are not segmentation boundaries. Select the required Scripture
branches and reassemble their adjacent fragments in document order before identifying
atoms or chanted words. An atom is one written form between spaces or maqaf marks. A chanted
word is one atom or a complete maqaf compound. Neither a storage fragment nor a
punctuation object becomes a separate atom or chanted word merely because it has its
own type. An lp-legarmeih node represents a mark that belongs with the preceding
atom. Narrow-sense paseq (lp-paseq) is not part of the preceding atom.
kq has exactly two children, kq-k (ketiv) and kq-q (qere). The ketiv is
unpointed and the qere is pointed.
The two children are in the order that MAM's rendered pages on Hebrew Wikisource have. Those pages have the ketiv first, except in 133 of the 1,047 pairs, counted on 2026-10-06, where they have the qere first: the pairs marked with MAM's קו״כ template, and three marked with a special template of the same kind. These pairs follow a maqaf or, in three verses, a narrow-sense paseq. MAM's introduction gives the reason for the maqaf case: the reading should not break after the maqaf. In Lam.1.18, for example, the qere completes the maqaf compound כׇל־הָֽעַמִּ֗ים:
[
{
"type": "text",
"text": "צַדִּ֥יק ה֛וּא יְהֹוָ֖ה כִּ֣י פִ֣יהוּ מָרִ֑יתִי שִׁמְעוּ־נָ֣א כׇל־"
},
{
"type": "kq",
"contents": [
{
"type": "kq-q",
"text": "הָֽעַמִּ֗ים"
},
{
"type": "kq-k",
"text": "עמים"
}
]
},
{
"type": "text",
"text": " וּרְאוּ֙ מַכְאֹבִ֔י בְּתוּלֹתַ֥י וּבַחוּרַ֖י הָלְכ֥וּ בַשֶּֽׁבִי׃"
}
]
MAM-simple marks these pairs only by the order of their children, so identify the ketiv and
the qere by object type, never by position. A reader that wants the rendered pages' order
keeps the document order; one with its own convention, such as the ketiv first throughout, can
impose it. MAM's wikitext, and so MAM-parsed, differ: every ketiv/qere template there lists the
ketiv first, and only the template's name, קו״כ or a סוג beginning קו״כ, says that the
rendered page has the qere first.
Both children usually have a text field, but not always:
kq-q may instead have children, when the qere spans a legarmeh or a paseq, e.g.
1Chr.27.12, where the qere contains a text object, an lp-paseq object, and another text object.kq-k may instead have an slh-word child. This happens once, at Job.7.5:{
"type": "kq",
"contents": [
{
"type": "kq-k",
"contents": [
{
"type": "slh-word",
"slhw-desc-0": "וגיש",
"slhw-desc-1": ".ג..",
"slhw-desc-2": "ק",
"slhw-desc-3": "ג/ק",
"contents": [
{
"type": "text",
"text": "ו"
},
{
"type": "letter-small",
"text": "ג"
},
{
"type": "text",
"text": "יש"
}
]
}
]
},
{
"type": "kq-q",
"text": "וְג֣וּשׁ"
}
]
}
So when reading a ketiv, try the text field first and fall back to assembling the
children. Do not silently skip a kq-k that has neither.
kq-trivial is for a ketiv/qere whose two forms differ in a way that needs no separate
display. kq-k-velo-q and kq-q-velo-k are the singletons: a ketiv that is not read,
and a qere that is not written. kq-k-velo-q-maq is a maqaf after a ketiv that is not
read, and occurs at 2Kgs.5.18 and 2Sam.13.33.
slh-wordslh-word wraps an atom one or more of whose letters is small (קטנה), large (גדולה),
or hung (תלויה). Its children spell the atom out, with each such letter in a
letter-small, letter-large, or letter-hung object. It also has four
description fields:
| Field | Meaning | Example (Dan.6.20) |
|---|---|---|
slhw-desc-0 |
The whole atom, pointed | בִּשְׁפַּרְפָּרָ֖א |
slhw-desc-1 |
One character per letter: the letter itself where it is small, large, or hung, and . elsewhere; maqaf marks kept |
..פ.פ.. |
slhw-desc-2 |
One code per marked letter: ק small, ג large, ת hung |
קג |
slhw-desc-3 |
letter/code pairs, comma-separated |
פ/ק,פ/ג |
slhw-desc-0 is the field to reach for when you want the atom as text and do not
care which letters are marked.
The children and slhw-desc-0 are two representations of the same atom-form. Consume
the children when letter formatting matters or slhw-desc-0 when an uninterrupted
atom-form is enough; never append both to the running text.
slh-word appears inside verse, and also inside kq-k, sdt-note, and
sdt-target.
scrdfftarscrdfftar has a sdt-target, which is the text the note is about, and a
sdt-note, which is the note. Its sdt-starpos field is before-word or
after-word, and says on which side of the target the note's marker belongs:
{
"type": "scrdfftar",
"sdt-starpos": "after-word",
"contents": [
{
"type": "sdt-target",
"text": "עַל־הָאָֽרֶץ"
},
{
"type": "sdt-note",
"contents": [
{
"type": "text",
"text": "בספרי תימן "
},
{
"type": "slh-word",
"slhw-desc-0": "הָאָֽרֶץ",
"slhw-desc-1": "...ץ",
"slhw-desc-2": "ג",
"slhw-desc-3": "ץ/ג",
"contents": [
{
"type": "text",
"text": "הָאָֽרֶ"
},
{
"type": "letter-large",
"text": "ץ"
}
]
},
{
"type": "text",
"text": " בצד״י גדולה"
}
]
}
]
}
cant-all-threecant-all-three has exactly three children, cant-combined, cant-alef, and
cant-bet, giving two strands and their combined representation of the same consonantal text. It appears in the
two Decalogues, Exod.20 and Deut.5, where MAM has both the תחתון cantillation
(cant-alef) and the עליון one (cant-bet). It also appears at Gen.35.22, where MAM
has both the פשוטה cantillation (cant-alef), whose chanted verse ends before the
petuḥah inside the numbered verse, and the מדרשית one (cant-bet), whose chanted verse
runs on past it. Wherever it appears, cant-combined is a combined representation of the two strands;
it need not include every mark of each strand.
good-endinggood-ending has the verse that is repeated after the last verse of a book, so that
the reading ends on a favorable note. It occurs at the end of the four books that have
this custom: Isa.66.24, Mal.3.24, Eccl.12.14, and Lam.5.22.
class fieldsThree objects take an optional class field:
| Element | class |
Meaning |
|---|---|---|
kq |
sep-maqaf |
Separate ketiv from qere with a maqaf rather than a space (1Chr.9.4, Isa.26.20) |
spi-invnun |
including-trailing-space |
The marker includes a trailing space |
spi-samekh3 |
nu10-invnun-neighbor |
The setumah adjoins an inverted nun of Numbers 10 |
| Field | Meaning |
|---|---|
osisID |
OSIS-format reference (e.g., Job.34.24) |
text |
Full verse text (only present for simple verses) |
starts-with-sampe |
Verse starts after a parashah marker (pe2, samekh2, etc.) |
ends-with-sampe |
Verse ends with a parashah marker |
contents-corresponds-to |
Versification note |
osisID-of-MAM-src |
Source verse in MAM's native versification |
osisID is on every verse. The last two fields never appear in vtmam.
A yeivinID field sat beside osisID until 2026-09-12, on every verse of the
vtmam files and on no verse of the vtbhs or vtsef ones. It gave Yeivin's spelling
of the very same chapter and verse — Job 34:24 beside osisID Job.34.24 — and it
was retired because that is all it ever was: checked across all 23,202 of them, the
chapter and verse always matched, and the book abbreviation came from a fixed one-to-one
table of the 39 books, which is still at py/ in
MAM-basics. A reader that wants Yeivin-format references can build them from the
osisID and that table.
starts-with-sampe and ends-with-sampe take a bare marker name — pe2, pe3,
samekh2, samekh3 — rather than the spi- prefixed object name.
The BHS and Sefaria versions describe the way in which their versifications
differ from MAM's native versification via two verse fields:
contents-corresponds-to and osisID-of-MAM-src.
Here are three abbreviated examples, using JSON:
[
{
"type": "verse",
"osisID": "1Sam.24.1",
"contents-corresponds-to": "a full verse in MAM",
"osisID-of-MAM-src": "1Sam.23.29"
},
{
"type": "verse",
"osisID": "Deut.5.7",
"contents-corresponds-to": "less than a full verse in MAM",
"osisID-of-MAM-src": "Deut.5.6"
},
{
"type": "verse",
"osisID": "Josh.21.36",
"contents-corresponds-to": "no verse in MAM"
}
]
The contents-corresponds-to field can take on one of three values:
a full verse in MAMless than a full verse in MAMno verse in MAMThe osisID-of-MAM-src field complements the first two cases
above. It says which verse in MAM this verse fully or partially
corresponds to. It is absent in the third case, no verse in MAM,
there being no source verse to name.
For a description of every place where the three versifications differ, see Versification differences.