Reading MAM-parsed-plus

The MAM-parsed-plus JSON files are formed by: (a) parsing the Wikitext downloaded from Hebrew Wikisource, (b) adding some conveniences and (c) removing some inconveniences. Of course, what is considered an inconvenience and what is considered a convenience can only be determined relative to a particular application. Nonetheless, we’ve tried to make MAM-parsed-plus convenient to use for a broad variety of applications. This document covers:

• File naming
• Structure of the top level and its header
• Structure of a book39, chapter, and verse
• Template format
• Selected templates

For guidance when writing code to use the data, see Notes for applications.

File naming

File names (e.g. A1-Genesis.json) start with two characters that identify the book (in the “24 books” sense) and provide a standard ordering. The first character (sec_char) comes from the set ABCDEF and indicates the section of Tanakh. The second character (book24_char) comes from the set 12345AC and indicates the book within that section.

Files are named {sec_char}{book24_char}-{EnglishName}.json:

When book24_char is A or C, the file is for a book24 with sub-books (e.g. BA-Samuel has sub-books 1 Samuel and 2 Samuel). The letter B is not used in order to keep compatibility with a set of codes used for the 39-book system.

Top-level structure

{
  "header": {...},
  "book39s": [...]
}

Header

Here’s the header for Job, a book24 that has no sub-books:

{
  "book24_name": "ספר איוב",
  "sub_book_names": [],
  "chapter_counts": [
    {
      "sub_book_name": null,
      "chapter_count": 42
    }
  ],
  "consumer_notice": {...}
}

Here’s the header for Samuel, a book24 that has sub-books:

{
  "book24_name": "ספר שמואל",
  "sub_book_names": [
    "שמ\"א",
    "שמ\"ב"
  ],
  "chapter_counts": [
    {
      "sub_book_name": "שמ\"א",
      "chapter_count": 31
    },
    {
      "sub_book_name": "שמ\"ב",
      "chapter_count": 24
    }
  ],
  "consumer_notice": {...}
}

Book39 structure

{
  "book24_name": "ספר ישעיהו",
  "sub_book_name": null,
  "chapters": {...},
  "good_ending_plus": {...}
}

Chapter structure

The chapters object is keyed by verse numbers. For example, a chapter with 22 verses has exactly 22 keys, "1" through "22".

Template format

Templates are represented like this:

{
  "tmpl_name": "קו״כ",
  "tmpl_params": {"1": "את", "2": "אַ֠תָּ֠ה"}
}

Numeric string keys "1", "2", … correspond to positional arguments, Non-numeric keys (e.g. "ד", "ס", "סדר") represent named parameters like ד=... in the Wikitext.

The tmpl_params object is absent when the template has no parameters (e.g. פפ, סס, מ:פסק).

Template parameter values can be complex

Parameter values can themselves be strings, nested template objects, or arrays mixing strings and templates. See the dedicated page on template nesting.

Example — a word with a special letter inside a ketiv/qere inside a נוסח:

{
  "tmpl_name": "נוסח",
  "tmpl_params": {
    "1": {
      "tmpl_name": "כו״ק",
      "tmpl_params": {
        "1": {
          "tmpl_name": "מ:אות-מיוחדת-במילה",
          "tmpl_params": {...}
        },
        "2": "וְג֣וּשׁ"
      }
    },
    "2": ...
  }
}

Verse structure

Each verse is a 3-element array for the separator, verse label, and verse proper. These positions retain the C, D, and E names used by a now-obsolete spreadsheet version of MAM.

• C — Verse separator: usually a plain space or a parashah break
• D — Verse label: empty unless more than book, chapter, and verse
• E — Verse proper: strings and templates

C column (index 0): Verse separator

Column C is an array indicating how this verse is separated from the preceding verse:

• Double underscore ("__") is by far the most common value. It indicates a plain space.
• Other common values are calls to the ר4 template, the פפ template, or the סס template. (See the Whitespace templates section below.)

D column (index 1): Verse label

Column D is an array that, if not empty, contains exactly one element: either a מ:פסוק template or מ:פסוק wrapped in a נוסח template. Column D is sparse: it omits source boundary records that do not supply retained label data:

• When Column D contains a direct (unwrapped) מ:פסוק, it always has at least one of the סדר or עלייה named params. Direct calls without named params do not appear, as they are considered uninteresting.
• When Column D contains a נוסח-wrapped מ:פסוק, the נוסח wrapper itself makes the entry interesting even if the inner מ:פסוק lacks named params.
• When there are neither named params nor נוסח wrapping, the array is empty.

For example, here is the D column value for Job 1:1, kept because of its סדר param:

[{
  "tmpl_name": "מ:פסוק",
  "tmpl_params": {"1": "איוב", "2": "א", "3": "א", "סדר": "א"}
}]

E column (index 2): Verse proper

Column E is an array mixing strings and templates. Example (Job 1:1):

[
  "אִ֛ישׁ הָיָ֥ה בְאֶֽרֶץ־ע֖וּץ אִיּ֣וֹב שְׁמ֑וֹ וְהָיָ֣ה",
  {"tmpl_name": "מ:לגרמיה-2"},
  " הָאִ֣ישׁ הַה֗וּא תָּ֧ם וְיָשָׁ֛ר וִירֵ֥א אֱלֹהִ֖ים וְסָ֥ר מֵרָֽע׃"
]

Selected templates

The following sections describe the templates selected for this data format. Hebrew Wikisource is the maintained textual source.

Verse label templates

Ketiv/qere templates

For קו״כ, MAM's rendered Wikisource page has the qere first, then the ketiv. This template is used where the pair follows a maqaf, and in three verses where the pair follows a narrow-sense paseq (מ:פסק): 1 Samuel 2:16, Jeremiah 4:19 and Ezekiel 35:12.

Example of standard ketiv/qere (Genesis 8:17):

{
    "tmpl_name": "כו״ק",
    "tmpl_params": {"1": "הוצא", "2": "הַיְצֵ֣א"}
}

Special letter templates

Punctuation and silluq-position templates

Choice templates

Most applications will need to make a choice between the two or three options presented by these templates.

Whitespace templates

A whitespace template can be the only separator between adjacent Scripture strings: the strings before and after מ:ששש or ססס can contain no literal whitespace at that boundary. A plain-text projection that does not preserve layout must therefore supply at least one separator; a layout-preserving renderer implements the documented space or break. Dropping the template fuses separate atoms, while collecting a descriptive parameter such as פסקא באמצע פסוק inserts documentation into Scripture. This rule does not apply to narpas: מ:פסק is a punctuation template, and its missing literal whitespace prescribes no display spacing.

When פפ, פפפ, סס or ססס marks a parashah break within a verse (rather than between verses), it takes the argument פסקא באמצע פסוק, with three rule-based exceptions in column E:

• a ססס between the items of a list (as in 2 Samuel 23; noted in MAM's Introduction)
• a break inside מ:כפול, tagged only in the strand where it falls within a verse
• the ססס beside an inverted nun, at the edge of a verse (Numbers 10:35–36)

Many editions will choose to skip poetic formatting by treating ר0–ר4 as simple word spaces.

Lack-of-whitespace templates

Note template

Documentation templates

For מ:קישור פנימי בהערה, parameter 1 is a Wikisource-internal target (path or fragment) rendered under https://he.wikisource.org/wiki/; for מ:קישור בהערה, parameter 1 is an external URL used as-is.

Silluq before meteg

Currently MAM has two annotated cases of silluq before meteg: 1 Kings 7:37 and Job 4:12. Each has exactly one meteg after silluq.

The template מ:סילוק לפני געיה identifies silluq before meteg without changing MAM’s text. For example, MAM’s annotation for Job 4:12 is:

{
  "tmpl_name": "מ:סילוק לפני געיה",
  "tmpl_params": {
    "1": "מֶֽנְהֽוּ",
    "2": "מֽנהו"
  }
}

Parameter 1 contains the full marked atom. Here, the stroke on מ is silluq, and the later stroke on ה is meteg. Both strokes use U+05BD.

Parameter 2 repeats the Hebrew letters with only the silluq stroke, identifying which stroke marks the stressed syllable.

The template takes exactly these two positional parameters. Parameter 1 includes the identified silluq and at least one later U+05BD. Parameter 2 contains no other marks or punctuation. The following sof pasuq sits outside the template as ordinary text.

A Scripture projection takes parameter 1 only. Parameter 2 is position metadata, not a second reading. A consumer that locates stress uses the explicit position instead of assuming that the final U+05BD is silluq.

Notes for applications

The notes below are for writers of programs that read ("consume") the JSON data. Such programs are the "consumers" named by the header.consumer_notice field. The notes are as follows:

This is a structured dataset, not ready-to-display Scripture; interpret each structure by its documented role and choose a projection wherever the payload presents alternatives.

• Use a closed, role-aware template dispatch: recurse only through documented Scripture-bearing fields, and fail on an unknown template instead of guessing from its parameters or skipping it.
• Choose one documented branch of each choice-bearing structure, including dual cantillation, qamats, and poetic stress-helper alternatives where present; do not concatenate the branches.
• A ketiv/qere template 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.
• A special-letter template's interrupted spelling and uninterrupted atom-form are two representations of one atom-form; select one text representation rather than collecting both.
• Reassemble text fragments before identifying atoms or chanted words; array, template, and element boundaries are not segmentation boundaries.
• Narpas (narrow-sense paseq, מ:פסק) forms no compound of any kind: only maqaf joins atoms into a chanted word. Within the Scripture stream, MAM encodes no whitespace before or after narpas; that absence expresses neither grouping nor a display-spacing preference. An edition chooses whether to display spacing before and/or after narpas, while an analytical consumer need not make a display-spacing decision.
• A whitespace template can be the only separator between adjacent Scripture strings: for example, מ:ששש and ססס can have no literal whitespace at that boundary. Do not drop the template or collect a descriptive parameter as Scripture. A plain-text projection that does not preserve layout must supply a separator; a layout-preserving renderer must implement the documented space or break. This rule does not apply to narpas, whose missing literal whitespace prescribes no display spacing.
• MAM's gray maqaf (מ:מקף אפור) is a template with no parameters, 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.
• For literal search, byte comparison, or MAM-compatible output, preserve MAM mark order or transform both sides deliberately; Unicode-normalized text can look identical while comparing differently.

Every generated MAM-parsed/plus/*.json file includes these notes in header.consumer_notice. Its documentation field is an absolute URL to this section.