Near-Aleppo JSON reference

Contents:

• How to read the JSON
• MAM's templates: evaluated away or kept
• Templates specific to near-Aleppo
• GAV notation and display
• The parameters near-Aleppo adds
• A character MAM-parsed-plus has only in a note body
• Notes for applications

How to read the JSON

Near-Aleppo largely shares MAM-parsed-plus's structure, so MAM-parsed-plus's documentation is the reference for that shared structure and for the meanings of MAM's templates. This section describes near-Aleppo's template differences and added parameters.

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

MAM's templates: evaluated away or kept

Evaluating away a template replaces its wrapper with the selected text or character. The table shows the selected result or retained template, including the special-letter templates near-Aleppo keeps.

The following templates are kept unevaluated:

• נוסח
• מ:הערה-2
• מ:קו״כ-אם-2
• כו״ק
• קו״כ
• מ:כו״ק מיוחד
• כתיב ולא קרי
• קרי ולא כתיב

In נוסח and מ:הערה-2, the target is the first parameter. Templates within the target are evaluated away or kept unevaluated by the same rules as templates in the verse itself. Notes whose targets remain unchanged keep their source body in parameter 2. Changed notes store the reviewed near-Aleppo clause in parameter 2 and the remaining original clauses in their MAM-note parameter, including templates within them. Templates evaluated away in the verse remain unevaluated in those stored source clauses. This preserves MAM's quotations of readings from other editions. The HTML edition renders those retained templates when displaying the note.

In the ketiv/qere templates in this list, templates within every parameter follow the verse's rules for evaluation or retention, including parameters for readings that near-Aleppo does not select.

These examples show MAM templates in compact Wikitext syntax beside the text near-Aleppo has. The punctuation examples include adjacent text so the spacing is visible.

* Qamats qatan is shown upside down here for clarity.

In the מ:קמץ example, evaluation selects parameter ד. That parameter has HEBREW POINT QAMATS QATAN; the final near-Aleppo text has HEBREW POINT QAMATS under its qamats policy.

A ketiv/qere template's parameters other than the one near-Aleppo's text follows use the same rules. In those parameters, near-Aleppo evaluates away 1 מ:קמץ, 4 מ:דחי, 1 מ:לגרמיה-2, and 1 special-letter template besides. So מ:קמץ, מ:דחי, מ:צינור, מ:כפול, and מ:מקף אפור occur nowhere in near-Aleppo's text, in no column, parameter, or note body; only the copies of MAM's target have them.

Where MAM has a legarmeh, מ:לגרמיה-2, or a narrow-sense paseq, מ:פסק, near-Aleppo writes the same character, U+05C0, so its text does not tell the two apart. The note bodies, which near-Aleppo keeps verbatim, still have both templates.

Templates specific to near-Aleppo

Near-Aleppo uses three added templates, which MAM's text never has. Each name is specific to the near-Aleppo dataset, and none has the prefix מ: that marks many of MAM's.

Two are MAM's note templates under names specific to near-Aleppo. Where near-Aleppo changes a note's target, the JSON dataset stores the reviewed near-Aleppo clause in parameter 2 and MAM's target in an added parameter, מקרא על פי המסורה. The remaining original clauses are stored in הערת מקרא על פי המסורה and describe that MAM target. Such a note is renamed, so that a consumer who knows only MAM's templates fails on it rather than misreading it: a נוסח is named נוסח עם הקשר מקרא על פי המסורה, at 1,543 notes, and a מ:הערה-2 is named הערה-2 עם הקשר מקרא על פי המסורה, at 5. Scroll-note parameter 3 and the evidence flags keep their existing roles. So every template of MAM's that near-Aleppo has keeps MAM's meaning.

The stored near-Aleppo clause is already recast as an agreement with that form, retaining its explanations and qualifications. Where a recast would require uncertain interpretation, parameter 2 is an empty array and the complete original note is stored in the MAM-note parameter. Consumers can render both note roles directly from the book JSON; no review-ledger lookup or clause transformation is required. The example HTML edition displays the near-Aleppo clause beside its form, then MAM's labelled form and the stored MAM clauses.

The third template represents marks without a written letter. Its position, accepted carrier forms, and display are explained in GAV notation and display.

GAV notation and display

Position: the near-Aleppo dataset's ניקוד בלי אות represents marks at a position of nonzero width. Its name describes the position, not the carrier letter.

Carrier forms: the supported template accepts GA {"1":"אֵ"} or GV {"1":"וֹ","carrier":"holam-male-vav"} as its tmpl_params. GA permits one or more artificial alefs, each followed by permitted marks. GV requires exactly VAV + HOLAM and the carrier=holam-male-vav discriminator. Neither carrier permits a dagesh. The carrier parameter is semantic metadata; it identifies the holam-male carrier and is not Scripture text.

Display: GAV (guillemet-alef-vav) notation identifies artificial carriers, which are not written ketiv letters. JSON stores the template payload; the example edition supplies guillemets, as in «אֵ» and «וֹ». An adopted GV retains «וֹ»; converting it to «אֹ» loses the chosen holam-male distinction. Surrounding separators remain explicit strings or whitespace templates; an orphan template inserts no automatic space.

The supported nonzero-width template occurs at Genesis 14:2, 14:8, 25:23; Judges 11:37; 1 Samuel 13:8, 14:32, 17:23, 20:2; 2 Samuel 3:3, 18:3, 20:5, 21:9, 21:20, 22:8, 22:51, 23:9 (twice); 1 Kings 4:7, 7:20, 9:18, 15:18, 16:26; 2 Kings 4:5, 5:25, 9:15, 11:4, 11:9, 11:10, 11:15, 11:20, 12:12, 15:25, 17:31, 18:27 (twice); Isaiah 3:16, 25:10, 28:15, 32:15, 36:12, 42:20, 55:13; Jeremiah 10:13, 17:19, 18:23, 29:23, 40:3, 42:6, 48:7, 52:32; Ezekiel 16:20, 16:25, 16:51, 18:20, 25:9, 36:13, 36:14, 36:15, 42:9, 44:24, 46:19; Hosea 10:10; Psalms 56:7, 72:17, 92:16, 140:11; Proverbs 6:14, 16:27, 23:24, 23:31, 27:24; Job 2:7, 24:6, 33:19, 33:28 (twice); Ruth 2:1, 3:3; Lamentations 1:18, 2:2, 3:20, 4:16, 5:3, 5:5, 5:7 (twice); Ecclesiastes 4:8; Esther 10:1; Daniel 2:9, 2:22, 2:43, 9:12; Ezra 7:25; Nehemiah 12:16; 1 Chronicles 12:16; 2 Chronicles 9:29, 18:8, inside the pointed ketivs.

The original GA example, at Isaiah 36:12, is «אֵאֵ֥». Near-Aleppo encodes the bracketed alef carriers supplied in MAM's note; they are not written ketiv letters.

For an orphan holam associated with a qere vav where the ketiv has yod, an edition can choose among these display options:

• Show GAV directly, retaining the GV carrier before the ketiv yod.
• Collapse the holam backwards onto the consonant before the ketiv yod.
• Attach U+05B9 HEBREW POINT HOLAM to the ketiv yod as a rendering accommodation, without asserting that the yod owns the mark.

These display accommodations preserve the stored carrier meaning. Their visual acceptability depends on the font and rendering system. Prepared markup could let CSS select among display forms or position the dot. CSS alone does not reorder the Unicode text, and hiding a carrier does not reliably reattach its combining mark to another letter.

Unicode's Hebrew specification, “Holam Male and Holam Haser” uses U+05B9 for holam male on vav when the distinction is made. U+05BA HEBREW POINT HOLAM HASER FOR VAV distinguishes holam on consonantal vav; its use on other base letters is undefined. U+05B9 is also the ordinary holam on other letters. Unicode thus has no separate, letter-independent holam-male dot that would express the qere-vav role when attached to ketiv yod. Applying U+05B9 to yod can display the dot, but does not encode that role. A hypothetical letter-independent holam-male dot could make that intention explicit even on yod. The mismatch concerns encoded meaning, not a general Unicode ban on nonstandard letter-mark sequences.

The parameters near-Aleppo adds

Near-Aleppo adds six parameters to templates. Five accompany MAM's parameters; the sixth identifies the explicit GV variant of near-Aleppo's own orphan-mark template.

The parameter מקרא על פי המסורה, MAM's name for its text, holds MAM's target. Every note whose target near-Aleppo changes has it, and is renamed, as the previous subsection says: 1,548 notes. The original clauses in הערת מקרא על פי המסורה have MAM's text as their subject. A clause opening with = in that parameter says that the sources it names agree with MAM. A clause opening with the same sign in parameter 2 instead describes agreement with near-Aleppo's target. The MAM-target parameter holds MAM-parsed-plus's target verbatim, templates included, so it has templates that occur nowhere else in near-Aleppo: מ:קמץ, מ:דחי, מ:צינור, and מ:מקף אפור.

The two flags mark a reading of the codex that one of MAM's notes gives and that near-Aleppo treats specially. applied-and-flagged marks a reading near-Aleppo takes although the note marks it with a ! as a manifest error in the codex, so that near-Aleppo reproduces the scribe's slip and can be reversed: 90 of them. flagged-not-applied marks a reading near-Aleppo does not take, being marked with a ? as doubtful, or outweighed by the note's prose, or a site where MAM's apparatus does not say what the codex has: 66 of them. A flag is a parameter of the note whose clause motivates it, and its value is that clause, copied from the note's body; at a site with no such clause, the flag is a parameter of the ketiv/qere template concerned, and its value is one of two fixed sentences: “MAM's apparatus does not say whether the codex has a qere note here”, and “MAM's apparatus does not say whether the codex has the maqaf here”.

At Ezekiel 28:22, one note reports a missing holam as a manifest error in Aleppo. Near-Aleppo takes that form, with applied-and-flagged. Parameter 1 has the near-Aleppo form; מקרא על פי המסורה has the MAM form:

The flag value copies the original clause, including its exclamation mark. Parameter 2 already contains the reviewed agreement with near-Aleppo. The remaining original clauses are stored separately with MAM's target.

At 1 Kings 20:29, the flagged-not-applied value copies a doubt-marked clause. Near-Aleppo retains the target's maqaf and meteg; the alternative has a space and merkha:

The alternative remains unresolved and is not applied.

The parameter כתיב מנוקד holds a pointed ketiv from MAM's notes, approved frozen inference, individual adjudication or a sealed reviewed portable decision, at a ketiv/qere template of the families כו״ק, קו״כ, and מ:כו״ק מיוחד. It is the branch of the template that near-Aleppo's text follows, in place of MAM's pointed qere. Near-Aleppo has it at 1,032 templates, in 922 verses: 869 כו״ק, 127 קו״כ, and 36 מ:כו״ק מיוחד.

The parameter carrier=holam-male-vav identifies the narrowly licensed GV variant of the orphan-mark template. Its parameter 1 must be exactly VAV + HOLAM. The carrier parameter is metadata; the artificial vav represents orphan holam and is not a written ketiv consonant.

A character MAM-parsed-plus has only in a note body

One character of near-Aleppo's text is a character that MAM-parsed-plus has only in a note body: U+200C ZERO WIDTH NON-JOINER, at Job 38:12, in the pointed ketiv that the note there gives the codex, between the ketiv's tav and he. The note's form has it, and it is there to keep fonts from treating the he's patah as a furtive patah.

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:

The near-Aleppo dataset is similar to MAM-parsed-plus. The Hebrew of near-Aleppo is nearer to the Aleppo Codex's body text than the Hebrew of MAM-parsed-plus. Like MAM-parsed-plus, it 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. Beside MAM's templates, near-Aleppo uses three added templates: נוסח עם הקשר מקרא על פי המסורה and הערה-2 עם הקשר מקרא על פי המסורה, which are MAM's נוסח and מ:הערה-2 where near-Aleppo has changed the note's target. Their parameter 1 is near-Aleppo Scripture, and parameter 2 already contains the reviewed near-Aleppo clause, or an empty array when the complete original note remains in MAM context. הערת מקרא על פי המסורה holds the remaining original MAM clauses, in their original order, or that complete note. Consumers need no review ledger or editorial recasting to render these roles. The third added template is ניקוד בלי אות, which holds marks without a written letter at a position of nonzero width. It accepts GA: one or more artificial alefs, each followed by permitted marks; or GV: parameter 1 exactly VAV + HOLAM, with carrier=holam-male-vav. Neither carrier permits a dagesh. Carrier letters are not written ketiv consonants. JSON stores the carrier payload; the example edition supplies guillemets, retaining an adopted GV as VAV + HOLAM. Converting it to ALEF + HOLAM loses the chosen holam-male distinction. Surrounding separators remain explicit; no automatic space is inserted.
• Near-Aleppo adds six parameters. Five are not Scripture: מקרא על פי המסורה, on the two renamed notes, holds MAM's target; הערת מקרא על פי המסורה contains the source clauses about that target; and applied-and-flagged and flagged-not-applied, on a note or a ketiv/qere template, are apparatus; carrier, on the explicitly licensed orphan-mark variant, is semantic metadata identifying its artificial carrier. Use it to interpret the payload; do not collect it as Scripture text. The sixth, כתיב מנוקד, on a ketiv/qere template, holds a pointed ketiv from MAM's notes or the approved frozen inference from MAM's ketiv and pointed qere, or an individually adjudicated codex reading, or a sealed reviewed portable decision, and is Scripture.
• Choose one documented branch of each choice-bearing structure; do not concatenate the branches. Near-Aleppo has evaluated away MAM's templates for dual cantillation, qamats, and poetic stress-helper alternatives, so the branches left in near-Aleppo's text are those of the ketiv/qere templates, כתיב מנוקד among them, and of the special-letter words it keeps. A copy of MAM's target in מקרא על פי המסורה keeps all of MAM's alternatives.
• A special-letter template's interrupted spelling and uninterrupted word-form are two representations of one word-form; select one text representation rather than collecting both.
• Reassemble text fragments before identifying words or maqaf compounds; array, template, and element boundaries are not segmentation boundaries.
• 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.
• Outside note bodies, flag values, and the copies of MAM's target, which quote MAM, near-Aleppo writes U+05C0 HEBREW PUNCTUATION PASEQ for both narrow-sense paseq and legarmeh, erasing the distinction present in MAM. Near-Aleppo writes U+05C0 directly after its word and followed by a space or a whitespace template. U+05C0 forms no compound: only maqaf joins words into a chanted word. This describes the JSON; the example HTML edition adds a thin space before U+05C0 for display.
• Outside note bodies, flag values, and the copies of MAM's target, which quote MAM, near-Aleppo has no HEBREW POINT QAMATS QATAN, the codex having no separate sign for the qamats qatan, so its HEBREW POINT QAMATS is an ambiguous qamats, not a qamats gadol.
• 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. Near-Aleppo runs no normalization over MAM's strings, and keeps MAM's mark order and its COMBINING GRAPHEME JOINERs outside the added inferred-pointing parameters, which preserve their frozen source-owned output order.

Every book file of near-Aleppo includes these notes in header.consumer_notice, adapting MAM-parsed-plus's guidance to near-Aleppo. The documentation field links this section at https://bdenckla.github.io/MAM-basics/near-aleppo/reading-json.html#consumer-notice.