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

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

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

Special letter templates

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

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

Lack-of-whitespace templates

Note template

Documentation templates

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

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 ketiv/qere, dual cantillation, qamats, and poetic stress-helper alternatives where present; do not concatenate the branches.
• 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.
• 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.