scrollmapper/bible_databases: Bible Texts and Cross-References

scrollmapper/bible_databases scope and users

scrollmapper/bible_databases addresses the problem of obtaining Bible texts in structures that applications can ingest without writing a conversion layer for every translation. It is a data repository rather than a documented runtime service. The README directs developers to the `formats` folder for Bible-version databases, the `sources` folder for source texts and resources, and the `scripts` folder for production and conversion scripts.

The repository is relevant to engineers building searchable Bible readers, research applications, linguistic tools, reference viewers, and offline datasets. Its value lies in the range of representations: MySQL, SQLite, CSV, JSON, YAML, TXT, MD, and PARQUET. A desktop application might use SQLite, a data-processing service might consume CSV or JSON, and an analytical workload might read PARQUET. The repository does not prescribe one universal workflow.

The README lists 140 translations. They include English versions such as `KJV`, `ASV`, `BSB`, and `NHEB`, alongside translations identified with language labels including Albanian, Cherokee, Chinese, Greek, Croatian, Czech, Dutch, French, German, and others. The catalog also includes `KLV`, described as a Klingon-language version of the World English Bible. This is broad textual coverage, but it does not imply that every version contains the same books, annotations, or metadata.

Several catalog entries have important boundaries. `Anderson` is described as an 1864 New Testament, `BeaMRK` covers the Gospel of Mark, and some entries are described as only scripture portions. `KJV` is listed with Strong's numbers, morphology, and catchwords, while `Byz` is described as a Greek New Testament in the Byzantine textform. Developers must select by identifier and documented coverage, not only by the translation's display name.

Repository data flow from sources to formats

The repository layout describes a source-to-distribution pipeline. Source texts and resources are kept under `sources`. Conversion and production logic is placed under `scripts`, while database files available for use are organized under `formats`. This division makes the generated output distinguishable from the resources used to produce it.

The README names eight output formats, but it does not provide a complete field-level schema in its main page. It instead links to the project documentation at `docs/README.md`. Consequently, format selection alone does not establish table names, column names, reference representation, or optional fields. Those details need to be checked against the current documentation and the selected data file before application code is written.

The top-level repository also includes `generators`, `misc`, and `tests`. Their names indicate supporting work, auxiliary resources, and automated checks, although the README does not define a public command-line interface for any of them. The repository should not be confused with a conventional Python package. Although `requirements.txt` lists `future`, `mysql-connector-python`, `pyarrow`, `pymysql`, `pysword`, and `PyYAML`, the README does not document an importable Python API such as `import bible_databases`.

Cross-references form a second data layer. The README states that a large and accurate cross-reference resource is included from OpenBible's cross-reference project. It does not say that every translation database contains the same cross-reference fields, nor does it establish that cross-reference data is emitted in every supported format. An application requiring cross-references must verify their presence and structure separately from the Bible text file.

Selecting SQL, PARQUET, and text formats

SQLite is a reasonable candidate for a self-contained local database because it keeps access within a file-oriented application. MySQL becomes relevant when the Bible data must be loaded into a database server shared by other services. The README names both engines and the Python dependencies include database connectors, but it does not include a documented schema or a ready-made loading tutorial. A user must still inspect the files and current documentation.

CSV and JSON are explicit interchange choices. They can fit pipeline stages and application fixtures, but they do not enforce reference relationships or a verse-level schema by themselves. YAML and Markdown are also listed, which may suit documentation-oriented workflows, although the README does not say whether every translation is actually present in each format. Directory inspection is therefore necessary before assuming uniform format coverage.

PARQUET is the only explicitly named columnar format. Its presence, along with `pyarrow` in `requirements.txt`, indicates support for column-oriented processing. The README does not state whether Parquet files include compression settings, partitioning, nested reference structures, or a stable field convention. Developers using it should inspect the actual files and tests rather than infer a schema from the extension.

A sensible selection rule follows from the repository's documented organization: first choose the required translation and fields, then confirm that the desired format is present, then verify its schema in `docs/README.md`. This order avoids selecting a convenient format before confirming that it actually contains the required text or cross-references.

Installing repository files and beginning inspection

The README does not provide a `pip install` command, release artifact, or first-run CLI example. The repository should be obtained from its GitHub location and inspected through the documented directories. The GitHub project page is therefore the starting point, while `docs/README.md` is the named source for usage documentation.

The repository includes a `requirements.txt` file. It lists the following Python dependencies:

future
mysql-connector-python
pyarrow
pymysql
pysword
PyYAML

The README does not specify a Python version, installation command, virtual-environment command, or executable entry point. It would therefore be inaccurate to supply a `pip install` line or claim that the project exposes a public CLI. Install or execution depends on which documented conversion or validation process an application intends to use.

For a first real use, select a known translation such as `KJV`, locate its available database under `formats`, and inspect its structure before importing it. The README does not state the exact filename or provide a ready query, so an invented path or SQL statement should not be substituted. Confirm the reference format, optional annotations, and encoding against the current documentation. This produces a verifiable foundation for application integration.

The 2024 and 2025 schema boundary

The most important migration issue is explicit. The README says that the legacy version is available on the `2024` branch. It also warns that significant database schema changes were implemented in the `2025` branch and subsequent versions. Code or ETL logic written for the legacy structure should not be assumed to work with the current schema.

This distinction can affect more than a version number. Table names, column names, reference fields, annotation placement, or database layout may differ. The README does not publish a migration matrix, compatibility statement, or rollback procedure. It also does not explain how to translate an application from the legacy schema to the current one. The branch-specific documentation and selected database files are therefore necessary for any migration assessment.

The repository has no GitHub releases, so published release notes are not available as migration milestones. The repository is not archived, and its last push was on 2026-07-10. That is recent repository activity, but recent commits do not by themselves guarantee schema stability. A production consumer should identify the exact commit used for its data and application, especially when current development is not aligned with the legacy branch.

New projects should inspect the current branch before designing a schema adapter. Existing projects should determine which branch produced their existing files before reusing queries or conversion code. The README's warning makes this branch check a prerequisite, not an optional maintenance task.

Validation limits across translation editions

A large catalog creates more cases to validate than a repository containing one edition. Some listed translations include only part of the Bible. Others add Strong's numbers, morphology, catchwords, apocryphal content, transliteration, or original-language material. Absence of such a feature may reflect the edition rather than missing conversion, so hard-coded assumptions can misrepresent the source text.

The README's translation list gives language labels, but it does not define a documented uniformity guarantee for books, chapter counts, verse identifiers, optional annotations, or null handling. It also does not state how edge cases such as partial editions should be represented in application interfaces. Those questions should be answered from the database files and current documentation.

Cross-reference validation is equally important. OpenBible is identified as the source of the included resource, but the README does not specify whether records are normalized for every translation or exposed identically in each output format. If an application permits navigation to cross-references, it needs to verify that a reference resolves to content present in the selected edition. A cross-reference to a book absent from a partial New Testament dataset would otherwise become a broken navigation path.

The repository's `tests` directory is visible, but the README does not state which translations or formats are covered by those tests. Developers should not use the directory's existence as proof that every catalog entry passes the same validation rules.

Licensing, maintenance, and upgrade cost

The project is distributed under the MIT license. That defines the repository's project-level licensing terms, but the Bible translations themselves come from separate textual sources. The README lists source resources but does not provide a complete per-translation license table in the main documentation excerpt. An organization redistributing selected databases should therefore review both the repository license and the terms associated with the underlying translation.

Maintenance activity is recent. The repository is not archived, and the last push was on 2026-07-10. However, the project has no GitHub releases, so it does not offer a release-based upgrade channel visible in the repository metadata. Consumers may need to track the default branch or pin their work to a commit. That increases upgrade-control work for applications that require reproducible datasets.

The requirements file can also change the operational dependency set. `mysql-connector-python`, `pymysql`, `pyarrow`, `pysword`, and `PyYAML` are listed dependencies, but the README does not document their specific roles. The README does not pin versions, so an implementation must check the current `requirements.txt` when constructing an environment.

Schema migration is likely to be the larger adoption cost because the README explicitly announces significant changes after the 2024 branch. Organizations with an existing importer should budget time to compare schemas, remap queries, validate references, and confirm that the license and provenance of each translation remain acceptable.

Repository files versus API and private datasets

A real alternative is a maintained Bible API. The architectural difference is that scrollmapper/bible_databases distributes files through a repository, while an API exposes Bible content through network requests and a documented service contract. The API route may simplify a multi-user web application because the client does not need to manage database files. It also introduces service availability, network latency, request limits, and response compatibility into the application.

Another alternative is a private, application-specific database. Teams can normalize only the translations, books, annotations, and cross-reference relationships they need. This reduces catalog breadth and schema complexity, but it also means taking responsibility for conversion, updates, validation, and licensing review. The repository is more convenient when an application needs many editions or expects to regenerate formats from the included sources.

A local SQLite file is another possible approach for small or offline applications. Compared with MySQL, it avoids requiring a shared database server. Compared with CSV or JSON, it provides a database engine for querying and indexing. However, the repository still leaves schema inspection and edition validation to the adopter. The correct alternative depends on whether the priority is repository-based breadth, service access, or strict control over a reduced dataset.

Editorial conclusion

Adopt scrollmapper/bible_databases when your application needs a broad set of Bible translations or cross-reference data and can consume repository files. Do not treat it as a stable API, or replace legacy data with current files without checking the documented schema. Developers should first verify the intended branch, selected translation, available fields, format structure, and licensing of the underlying text.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. scrollmapper/bible_databases on GitHub