Abstract
Miqra according to the Masorah (MAM; מקרא על פי המסורה) is a digital edition of the Hebrew Bible designed to represent the Masoretic Text with attention not only to consonantal text, vocalization, and cantillation, but also to phenomena such as ketiv/qere, open and closed sections, unusual letter forms, distinctions between legarmeh and narrow-sense paseq, and alternative systems of cantillation. This article examines MAM from the perspective of computational reuse. It distinguishes the MAM editorial project from the machine-readable processing infrastructure currently surrounding it, particularly MAM-basics, MAM-parsed, and MAM-simple. The study examines the processing pipeline, textual hierarchy, representation of simple and structurally complex verses, semantic elements, versification mappings, and Unicode-ordering requirements of these resources. It argues that, for computational purposes, MAM is better approached not as a conventional relational database but as an editorial textual dataset accompanied by derived structured representations and a versioned processing/export pipeline. Particular attention is given to the consequences of this architecture for preservation, search, textual analysis, cantillation research, interoperability, and application design. The article concludes that MAM’s significance for biblical computing lies partly in its preservation of distinctions that would disappear if the Masoretic Text were reduced to a sequence of display strings.
Keywords: Miqra according to the Masorah; MAM; Masoretic Text; Hebrew Bible; biblical computing; digital humanities; text encoding; JSON; XML; OSIS; ketiv/qere; cantillation
1. Introduction: MAM as structured textual data
Digital editions of biblical texts are not simply electronic transcriptions of printed pages. Decisions concerning hierarchy, textual segmentation, annotation, character encoding, textual alternatives, versioning, and relationships among different reference systems determine what subsequent computational research can recover from the resource. Roorda’s account of the BHSA and Text-Fabric emphasizes that computational study requires representation of both the text and the information associated with it, while versioning becomes important when applications depend upon evolving scholarly datasets. Van Peursen and Kingham likewise describe the ETCBC Hebrew Bible as a searchable computational database containing morphological, syntactic, and text-level information rather than merely electronic prose. (ScienceDirect)
These considerations are especially relevant to the Masoretic Text. The Masorah concerns considerably more than a sequence of Hebrew consonants. Masoretic traditions encompass vocalization and accentuation as well as orthographic, reading, sectional, scribal, and textual phenomena. Ofer’s treatment of the Masorah, for example, discusses open and closed passages, the writing of biblical songs, ketiv/qere, and the roles of manuscripts such as the Aleppo and Leningrad codices. Digital representation therefore faces the problem of encoding distinctions whose significance may not be captured by the visible Unicode string alone. (Google Books)
Miqra according to the Masorah occupies this space as a digital edition of the Hebrew Bible. Seth (Avi) Kadish and Ben Denckla themselves describe MAM as an encoding of the Masoretic Text as a digital dataset, arguing that the Masoretic project is particularly suited to expression through structured digital data. (Hakirah)
The argument of the present study is therefore deliberately narrower than a general introduction to MAM. For software development and computational analysis, MAM is most usefully understood not as a conventional SQL-style database but as an editorial textual dataset surrounded by structured derived representations and a processing/export pipeline. This distinction explains both its computational potential and several requirements that downstream developers must observe.
It is also essential to distinguish the edition from the software infrastructure used to transform it. MAM refers here to the digital editorial project and textual data. The current MAM data attribution identifies Seth (Avi) Kadish as having prepared Miqra according to the Masorah from material originally developed at Hebrew Wikisource, with major technical assistance from Erel Segal-Halevi and Benjamin Denckla. MAM-basics, by contrast, is a software and data-processing repository associated with MAM; among its generated products are MAM-parsed, MAM-simple, MAM-for-Sefaria, and MAM-OSIS. Consequently, a structural rule documented for MAM-simple should not automatically be described as a property of the MAM editorial project itself.
2. Sources, versions, and method of examination
This article is an independent technical examination rather than documentation written on behalf of the MAM project. Because the processing ecosystem is actively developed, repository-specific observations were tied to a defined state of the source rather than treated as timeless properties.
The principal software source examined was the MAM-basics repository on its main branch at commit 0e63906d343ca3564517edc84eb91998f28f0d30, examined on 21 September 2026. That revision immediately followed a commit dated 20 September 2026. The repository describes itself as containing Python tools related to MAM and the products generated by those tools. (GitHub)
The examination covered the repository-level pipeline documentation; the current MAM-parsed documentation; the MAM-simple README and XML/JSON format descriptions; versification documentation; licensing information; and the Sefaria and OSIS export documentation. Representative generated data were also inspected directly. For example, the current Genesis JSON demonstrates both forms of verse representation discussed below: Genesis 1:1 is a structured verse containing an slh-word and letter-large, whereas Genesis 1:2 is represented directly by a text property. Genesis 1:5 additionally contains an lp-paseq node.
This study distinguishes three kinds of evidence: directly observed generated data, documented schema behavior, and project-reported corpus validation statistics. The distinction matters because a count reported by a generator’s documentation is evidence about the software’s validation process but is not equivalent to an independently reproduced corpus census.
A final pre-publication version should ideally add such an independent census. The reproducibility procedure supplied in the appendix is designed to count simple and complex verses and the frequency of structural node types from the pinned MAM-simple JSON corpus.
3. MAM and its machine-readable processing ecosystem
The present MAM-basics workflow begins with MAM’s Hebrew Wikisource data. Its documented pipeline downloads the Wikisource material, parses it into MAM-parsed/plain and MAM-parsed/plus, transforms MAM-parsed/plus into MAM-simple, and then derives additional Sefaria and OSIS products from MAM-simple. This architecture should be attributed to the processing infrastructure rather than retroactively to the editorial concept of MAM itself. (GitHub)
Conceptually, the current processing relationship can be summarized as follows:
MAM editorial text / Hebrew Wikisource
│
▼
MAM-parsed
┌─────┴─────┐
plain plus
│
▼
MAM-simple
┌────┴────┐
XML JSON
│
┌─────────┴──────────┐
▼ ▼
MAM-for-Sefaria MAM-OSIS
│
▼
SWORD usesMAM-parsed currently supplies two Wikisource-derived parsed representations. The plain representation remains comparatively close to the Wikisource material after conversion to the 24-book schema, whereas plus introduces additional processing, including information associated with favorable endings, targeted note templates, and marking of special-letter words, while removing some source-specific constructs. The documentation explicitly warns that the JSON structure of MAM-parsed is not yet stable. It is therefore more precise to describe MAM-parsed as a parse-tree-like structured source representation. Software engineers may find an analogy with an abstract syntax tree useful, but “AST” is not required as a formal description of the format.
MAM-simple, by contrast, describes itself as a simpler but incomplete representation of MAM. It is currently generated in XML and JSON, each under MAM-native, BHS, and Sefaria versification traditions—six format/versification combinations in principle. The BHS and Sefaria directories, however, are stored incrementally relative to the MAM-native files: all 24 book-group files occur in the MAM-native directories, while separate BHS and Sefaria files are stored only where their chapter/verse labels differ. A consumer requesting a missing BHS or Sefaria book group is instructed to fall back to the MAM-native file after verifying that the file’s versification-tradition includes the desired system. This arrangement resembles a delta-storage strategy, although that comparison is an analytical description rather than the formal name of the architecture.
The distinction between book24 and book39 should also be stated precisely. The outer grouping follows the traditional Jewish enumeration of twenty-four books, while internal book39 identifiers make possible the thirty-nine-book division familiar from the Protestant Old Testament. A single 24-book unit may consequently contain more than one book39 division.
4. Data model: hierarchy, simple verses, and structured verses
The application-facing MAM-simple representation has a hierarchy beginning with book24, within which one or more book39 units contain chapters and verses. Parashah markers can also occur at multiple positions in that hierarchy.
A simplified XML representation can be expressed as:
<book24 versification-tradition="...">
<book39 osisID="Job">
<chapter osisID="Job.1">
<verse osisID="Job.1.1" ... />
</chapter>
</book39>
</book24>The JSON representation mirrors the XML hierarchy rather than defining a substantially different data model. This equivalence facilitates applications that prefer either XML tooling or JSON-oriented web and mobile development.
The most consequential feature for software is that a verse is not always a single string. MAM-simple distinguishes simple verses from complex verses. A simple verse stores its complete textual content directly:
{
"type": "verse",
"osisID": "Gen.1.2",
"text": "..."
}A verse containing encoded phenomena instead contains ordered child nodes:
{
"type": "verse",
"osisID": "Gen.1.5",
"contents": [
{"type": "text", "text": "..."},
{"type": "lp-paseq"},
{"type": "text", "text": "..."}
]
}This is not merely an illustrative abstraction: the current generated Genesis file displays exactly this contrast between direct-text and child-structured verses.
The XML documentation states an important invariant: an element possesses either a text attribute or children, never both. Consequently, a consumer reconstructing textual material must recurse through complex nodes rather than assuming that every verse has a directly retrievable string.
Even recursive concatenation is insufficient in every case. Some nodes contain alternatives or annotations rather than sequential running text. Examples include ketiv/qere, multiple cantillation forms, scroll-difference structures, and repeated favorable endings. A renderer must therefore interpret node roles rather than blindly concatenate every descendant. This distinction illustrates why MAM-simple should be considered structured textual data rather than a conventional verse_id → string dataset.
5. Masoretic phenomena as semantic structures
5.1 Ketiv and qere
MAM-simple represents ordinary ketiv/qere as a parent kq structure containing a written kq-k branch and a read kq-qbranch. Its documentation further distinguishes written-but-not-read and read-but-not-written cases. The ordinary ketivis unpointed while the qere is pointed, and either branch can itself contain additional structure in exceptional cases.
The implementation consequence is significant. There is no universally correct operation equivalent to “return all text below this node.” A diplomatic display may require the written form; a reading-oriented display may prefer the qere; a search engine may index both; and a textual-analysis system may explicitly compare the two. The data representation allows those decisions to remain downstream choices.
5.2 Legarmeh and narrow-sense paseq
MAM-simple also preserves a distinction that is not recoverable from the displayed character alone. lp-legarmeih and lp-paseq both render with Hebrew punctuation paseq, U+05C0, but their semantic roles differ: the former records a legarmeh within the cantillation system, while the latter records paseq in the narrower sense. Mapping both nodes immediately to the same character string therefore loses encoded editorial information.
The same documentation cautions against treating storage-node boundaries as word or cantillation segmentation. Textual fragments should first be reassembled in document order. An “atom” is defined relative to spaces or maqaf, while a chanted word may be an atom or a full maqaf compound. The current documentation explicitly states that narrow-sense paseq forms no compound and that only maqaf joins atoms into a chanted word. This rule is important for any program performing cantillation analysis.
5.3 Special letters and alternate cantillation
Special-letter words can preserve small, large, and suspended letters using dedicated structural elements inside slh-word. Alternate cantillation is likewise not forced into one flattened text. cant-all-three contains three alternatives—combined, alef, and bet forms—and is used for the alternate accentuation traditions represented in the Decalogue.
The current MAM-simple element inventory also includes structures for parashah markers, song spacing, inverted nuns, implicit maqaf, scroll-difference annotations, and repeated favorable endings. Because this inventory belongs to a moving software schema, a published article should identify the repository revision rather than imply that the names are immutable properties of MAM itself.
5.4 Parashah structure
Parashah boundaries illustrate another modeling problem. In MAM-simple, open and closed section markers can occur between book39 units, between chapters, between verses, or inside a verse. In addition, nearby verse objects may carry starts-with-sampe or ends-with-sampe attributes. The documentation explicitly cautions that these are multiple representations of the same break and should not be counted independently.
This design is relevant to the broader problem of textual overlap. Biblical structures do not always nest conveniently into a single hierarchy; DeRose’s discussion of OSIS emphasizes precisely the complications created when book/chapter/verse structures overlap with other textual organizations. MAM-simple’s treatment of section markers provides a concrete example of the general digital-humanities problem of representing structures that cannot always be reduced cleanly to one tree of textual containers. (ResearchGate)
6. Versification and reference mapping
MAM-simple currently represents three chapter-and-verse placement traditions: MAM-native, BHS, and Sefaria. Eighteen of the twenty-four MAM book groups are documented as sharing the same labels across all three systems. Numbers differs between BHS and the other two, while 1Sam-2Sam, Deuteronomy, Exodus, Jeremiah, and Joshua require distinct handling for both BHS and Sefaria.
Where a non-MAM versification relocates material, MAM-simple can use the attributes contents-corresponds-to and osisID-of-MAM-src. Documented cases distinguish a target verse corresponding to a complete MAM verse, part of a MAM verse, or no MAM verse. For example, the documentation maps BHS/Sefaria-style 1Sam.24.1 to MAM source 1Sam.23.29in the complete-verse case.
These mappings do not by themselves constitute a general-purpose crosswalk application. Rather, the encoded relationships could support a reference-crosswalk service. A downstream program could use them to translate references, identify shifted boundaries, or align external annotations whose source follows a different numbering tradition.
This illustrates a recurring principle of the resource: the dataset encodes information from which useful services can be built, but the service itself should not be conflated with the dataset.
7. Unicode and preservation considerations
The Unicode issue deserves particular attention because it can lead to silent data corruption or failed searches.
The current MAM-simple documentation states that its Hebrew combining marks preserve MAM’s ordering rather than Unicode canonical ordering. In particular, shin dot, sin dot, dagesh/mappiq, and rafe have defined precedence within the source representation. The resulting text is therefore neither ordinary NFC nor NFD. Unicode normalization can change the underlying byte/codepoint sequence even when the text continues to appear visually identical.
For a scholarly implementation, two separate principles should therefore be distinguished.
Preservation rule. When preserving MAM, providing a byte-level round trip, or producing MAM-compatible output, the original MAM codepoint order should remain unchanged.
Derived-processing rule. An application may generate a transformed representation for searching, indexing, interoperability, or another explicitly defined purpose. In that case, transformation should be deliberate and reproducible, and both query and indexed data should be transformed according to the same documented procedure.
The project reports useful validation statistics for this property. Its current documentation records 337 relevant shin/sin-before-dagesh clusters and 8,325 dagesh-before-vowel clusters in Genesis, and totals of 4,836 and 122,797, respectively, across the twenty-four files of a MAM-simple flavor. These figures should be described as project-reported generator/validation statistics, not as measurements independently reproduced by the present study.
A robust search-oriented implementation might consequently retain fields conceptually resembling:
source_text exact MAM sequence
search_text documented transformed form
consonantal_text derived form without pointing
qere_search_text derived reading-form index
ketiv_search_text derived written-form index
accent_sequence derived analytical representationThe important point is not the particular database schema. It is that a convenience representation should be derived from, rather than substituted for, the preserved scholarly source.
8. Potential applications and design implications
The preceding sections describe documented characteristics of the current resources. The possibilities considered here are intentionally prospective: they are design implications, not claims about applications that MAM itself already provides.
8.1 Readers and APIs
For a relatively simple digital reader, MAM-simple JSON could be consumed directly without introducing a relational database. A static website, desktop application, or mobile application could load individual book-group files and render verses according to application-specific policies for ketiv/qere, special letters, and alternate cantillation.
Server-side systems requiring joins, annotations, synchronization, or advanced querying could instead import the hierarchy into SQLite or PostgreSQL. A useful implementation would retain the structural tree rather than reducing it to a table containing only book, chapter, verse, and text. Parent-child node relationships, ordered sibling positions, node types, textual values, and uncommon attributes could be stored relationally or with a combination of relational columns and JSON/JSONB.
The resulting representation would be an application-facing structured representation, not a new canonical textual authority.
8.2 Search
The structural encoding could support searches that differ from ordinary full-text lookup. An application might derive consonantal, pointed, accent-sensitive, ketiv, qere, or feature-based indexes. It could also query occurrences of particular semantic nodes—for example, suspended letters or narrow-sense paseq.
Such indexes should be explicitly derived layers. The preserved MAM text should remain separately available so that improved tokenization or normalization algorithms can regenerate the indexes without altering the underlying edition.
8.3 Cantillation research and teaching
The presence of Masoretic accentuation together with distinctions such as legarmeh versus paseq makes the data potentially useful for cantillation research or instructional software. A downstream program could reconstruct text fragments, segment chanted words, classify accents, and associate accentual patterns with pedagogical or musical information.
The documented warning about segmentation is essential here: element boundaries do not automatically define chanted-word boundaries, and only maqaf forms the documented compound relationship discussed above.
8.4 Reference alignment and corpus interoperability
Versification metadata could support services that align MAM-native references with BHS or Sefaria references. This may be especially useful when combining resources developed in different biblical-computing ecosystems.
The broader processing infrastructure already demonstrates interoperability in another sense. MAM-for-Sefaria is generated as a Sefaria-oriented extract, while MAM-OSIS is designed for conversion to SWORD. The present STEPBible version inventory continues to list the MapM module. These exports demonstrate that MAM-derived data can participate in existing Bible-software ecosystems, although an exported module should not automatically be assumed to expose every feature available in the richer source representations.
8.5 NLP and computational biblical Hebrew
MAM may also serve as a stable textual layer underneath independently generated linguistic annotations. Morphology, lemmas, syntax, translations, vector embeddings, or machine-learning predictions could be linked to MAM locations without being incorporated into the MAM text itself.
This separation follows a pattern familiar from other digital Hebrew Bible corpora. BHSA/Text-Fabric, for example, explicitly treats textual and annotation layers as computationally reusable data whose versions matter for reproducibility. (KNAW)
9. Evaluation: advantages, limitations, stability, and interoperability
From a downstream research perspective, the principal advantage of the MAM machine-readable ecosystem is not merely that it provides pointed Hebrew in JSON or XML. Its more important characteristic is the retention of distinctions that a flattened textual representation could erase. Ketiv/qere branches remain alternatives; legarmeh and paseq can remain semantically distinct even though their glyph is identical; unusual letters can remain structurally identifiable; alternate cantillation systems need not be collapsed; and versification relationships can remain machine-addressable.
This advantage carries an implementation cost. Consumers cannot safely assume that each verse is a string, concatenate every child node, identify word boundaries from XML/JSON node boundaries, or apply ordinary Unicode normalization without considering the project’s documented conventions. The resource therefore rewards role-aware processing but imposes more responsibility on developers than a simple verse-text dataset.
Schema stability also differs by representation. MAM-parsed currently states explicitly that its JSON format remains subject to change. MAM-simple is designed as a simpler downstream representation, but it too should be consumed against versioned documentation because the repository is under active development. This makes commit-pinned citations particularly important for reproducible scholarship.
The export products require a further qualification. As of the repository state examined here, the documentation states that MAM-for-Sefaria and MAM-OSIS have not been kept continuously current since 12 September 2026; they are regenerated deliberately and can therefore lag behind MAM-simple and MAM-parsed. This is precisely the sort of time-dependent fact that should appear in an article only with a version and access date.
Licensing also distinguishes code from textual data. The current MAM-basics repository licenses its code under GPL-3.0 while mapping textual datasets separately. The MAM material is identified there as CC BY-SA 4.0 and carries attribution requirements. Developers redistributing derived data should therefore treat licensing and attribution as part of the application architecture rather than as an afterthought. (GitHub)
A limited quantitative audit
The following table separates directly inspected behavior from statistics supplied by the project documentation.
| Observation | Result | Evidential status |
|---|---|---|
| MAM-native book-group coverage described by MAM-simple | 24 book groups | Project documentation |
| Book groups sharing MAM/BHS/Sefaria cv-label placement | 18 of 24 | Project documentation |
| Separate BHS divergence groups | 6 | Project documentation |
| Separate Sefaria divergence groups | 5 | Project documentation |
| Genesis 1:1 representation | structured contents; includes slh-word/letter-large | Direct inspection |
| Genesis 1:2 representation | direct text property | Direct inspection |
| Genesis 1:5 | structured verse containing lp-paseq | Direct inspection |
| Mark-order validation: shin/sin dot preceding dagesh, whole flavor | 4,836 clusters | Project-reported validation |
| Mark-order validation: dagesh preceding vowel, whole flavor | 122,797 clusters | Project-reported validation |
| Yeivin-style verse references checked before attribute retirement | 23,202 | Project-reported validation |
The current documentation reports that the 23,202 former yeivinID references were checked before that attribute was retired on 12 September 2026 and that chapter and verse values consistently matched the OSIS references. Again, this is useful evidence concerning the project’s validation procedure but should not be presented as an independent result of this review.
A stronger final publication should supplement this table with an independently executed whole-corpus census of kq, lp-legarmeih, lp-paseq, alternate-cantillation nodes, simple versus complex verses, and other node types.
10. Conclusion
Miqra according to the Masorah should not be reduced conceptually to a “Bible database” in the ordinary sense of rows containing references and Hebrew strings. MAM itself is an editorial digital dataset, while its present computational ecosystem includes a set of derived structured representations and transformation tools. The distinction between those levels is important both historically and technically.
The present processing infrastructure illustrates a progression from Wikisource-oriented source material through parsed representations to a simpler XML/JSON application layer and then to application-specific exports. Within MAM-simple, the fundamental computational object may be a structured textual tree rather than a string. That structure preserves distinctions involving ketiv/qere, parashah divisions, special letters, alternate cantillation, legarmeh/paseq, versification, and other phenomena that could otherwise disappear during flattening.
This architecture also imposes constraints. Consumers must distinguish sequential text from alternatives, reconstruct textual fragments before deriving linguistic segmentation, handle multiple versification traditions deliberately, preserve source codepoint ordering when fidelity requires it, and cite schema behavior against a specific software version. MAM-parsed’s explicitly unstable schema and the potentially lagging Sefaria/OSIS export products further reinforce the importance of versioned scholarly practice.
These characteristics place MAM within a wider digital-humanities problem: the scholarly text is not equivalent to the characters visible on a screen. As work on BHSA, Text-Fabric, OSIS, and theological markup has demonstrated, computational representation determines which textual structures can subsequently be queried, compared, reproduced, and preserved. (ScienceDirect)
For that reason, MAM’s computational importance lies not only in making the Masoretic Text digitally available, but in making significant parts of its internal structure computationally addressable. The most productive downstream architectures will therefore preserve the editorial data as a source layer and build search, linguistic analysis, cantillation tools, reference alignment, and user interfaces as explicitly derived layers around it.
References
- DeRose, Steven J. 2004. “Markup Overlap: A Review and a Horse.” Extreme Markup Languages 2004. (ResearchGate)
- Denckla, Benjamin. MAM-basics. GitHub repository, revision
0e63906d343ca3564517edc84eb91998f28f0d30. Accessed 21 September 2026. (GitHub) - Kadish, Seth (Avi), and Ben Denckla. 2025. “Miqra as Oral Torah, Written Torah, and Digital Torah.” Hakirah36: 39–77. (Hakirah)
- Kingham, Cody, and Wido van Peursen. 2018. “The ETCBC Database of the Hebrew Bible.” Journal for Semitics 27(1). doi:10.25159/1013-8471/2974. (Vrije Universiteit Amsterdam)
- MoChridhe, Race J. 2019. “Twenty Years of Theological Markup Languages: A Retro- and Prospective.” Theological Librarianship 12(1): 40–49. doi:10.31046/tl.v12i1.523. (ATLA Serials)
- Ofer, Yosef. 2019. The Masora on Scripture and Its Methods. Translated by Michael Glatzer. Berlin/Boston: De Gruyter. doi:10.1515/9783110594560. (Google Books)
- Roorda, Dirk. 2018. “Coding the Hebrew Bible.” Research Data Journal for the Humanities and Social Sciences3(1): 27–41. doi:10.1163/24523666-01000011. (ScienceDirect)
- Miqra according to the Masorah, Hebrew Wikisource and associated MAM data documentation. MAM data attribution: Seth (Avi) Kadish, with major technical assistance from Erel Segal-Halevi and Benjamin Denckla; CC BY-SA 4.0.
