Reading MAM-simple: JSON Format

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.

Root object

{
  "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.

Book39 objects

{
  "type": "book39",
  "osisID": "Ruth",
  "contents": [ "...", "...", "..." ]
}

The contents array contains chapter objects and parashah-marker objects.

Chapter objects

{
  "type": "chapter",
  "osisID": "Ruth.1",
  "contents": [ "...", "...", "..." ]
}

The contents array contains verse objects and parashah-marker objects.

Verse 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": " מַחְל֤וֹן ..." }
  ]
}

Parashah-marker objects

{ "type": "spi-pe2" }

Parashah-marker objects can appear:

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

Ketiv/qere objects

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.

Silluq before a later meteg

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.

Legarmeh and paseq

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.

Three invariants worth relying on

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/mb_cmn/uni_denorm.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.

How Verse Text Is Stored

Simple verses: text field

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

Complex verses: child objects

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": " הָאִ֣ישׁ הַה֗וּא תָּ֧ם וְיָשָׁ֛ר וִירֵ֥א אֱלֹהִ֖ים וְסָ֥ר מֵרָֽע׃"
    }
  ]
}

Extracting the plain text of a verse

  1. If the verse has a text field, that field is the whole plain text.
  2. Otherwise, walk its children in document order. Each child contributes either its 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

Child Object Types

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.

Ketiv/Qere

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:

{
  "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.

Suspended-letter words: slh-word

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

Scroll differences: scrdfftar

scrdfftar 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": " בצד״י גדולה"
        }
      ]
    }
  ]
}

Dual cantillation: cant-all-three

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

Repeated endings: good-ending

good-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 fields

Three 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

Verse Fields

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/py_misc/yeivin_book_abbrevs.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.

Versification Fields

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:

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