Freely-Given.org Bible Door Data Specifications

Picture of the FG Logo

Bible Door app

You may want to read the user overview page first and the app specs page as background before reading these detailed specifications.

Bible Door data format

The Bible Door export from the Bible Drop Box may also be usuable by other software, including web software, since it is JSON (see also here) and HTML5 based.

Please note that this particular JSON format is still tentative and subject to revision.

You can see some sample Bible Door data here and here.

All files are UTF-8 encoded (without BOMs), and using Linux/Unix-style (\n) line-endings. Update: We might be adding BOMs so software should be able to handle them if they’re there.

Server alive response

Firstly, the five-byte text file Links/FG_BD_Header.txt simply contains the word Alive, and may be downloaded to verify successful contact with our server.

Bible header

Secondly, the file BDHeader.json (typically under 250 bytes) may be downloaded from Links/(link code)/ e.g., Links/wycliffe-123-456/ and contains the following information:

Note that software should ignore (i.e., not crash) if it detects any new additional fields that it doesn’t yet know about.

File checksums

Thirdly, the file BDChecksums.1.json (typically around 8KB) may optionally be downloaded from the same location. Note that the .1 before the file extension (and at the end of the folder names below) matches the Data Format Version above. This file contains a dictionary/map of filenames and md5 checksums in hexadecimal. Each md5 checksum is a string containing exactly 32 hexadecimal characters.

For example:

Division names

Fourthly, the file BDDivisionNames.1.json (typically under 100 bytes) may be downloaded from the same location. This file contains an ordered array of major division names like the following (but often only with two entries being Old and New Testament names):

There are no parentheses in the actual data, for example:

Book names

Fifthly, the file BDBookNames.1.json (typically around 6KB) may be downloaded from the same location. This file contains an ordered array of array entries (for each included book) like the following:

For example:

where BBB is the three-character book code from the Bible Organisational System (BOS).

Note that the number of sections should equal the number of chapters if the translation does not include section headings.

Book data

Sixthly, you can choose between our compressed HTML5 data, regular JSON data, and (recommended) our newer TEXT data (loosely based on ESFM).

  1. Text (recommended)

    Found in folders ByBook.1.BDTXT. There are lots of pairs of .bd.idx and .bd.txt files, one for each book, e.g., DAN.1.bd.txt, typically around 4MB in total.

    Alternatively, the file AllBDTextFiles.bz2 is a compressed collection of all the text and index files, typically about 1MB to download. (The files are all together in a folder named AllBDTextFilesinside the .bz2 file.)

    1. Index files: These are named per book, e.g., GEN.1.bd.idx. These are JSON files, containing a list of lists. Each inner list entry contains either five or six integers:
      1. Start chapter number (-1 for book introduction)
      2. Start verse number (or line number for the introduction)
      3. File offset (to find the start of the section in the text file)
      4. Length of the text section
      5. End verse/line number
      6. (OPTIONAL) End chapter number (only if it’s different from the start chapter number).
    2. Text files: These are named per book, e.g., CO2.1.bd.txt and are loosely based on ESFM, but modified to allow for easier text processing.
      Each segment (section or chapter) can be extracted via the file offset and length from the index file.
      Each segment begins with a paragraph marker followed by an equals sign, e.g., q1=.
      Paragraph markers are normalised, i.e., always s1, never s.
      Chapter and verse numbers are surrounded by braces, are prefixed by a letter, are NOT surrounded by spaces (the app handles formatting), and are in the expected display position, e.g., p={c1}{v1}In the beginning.
      Only new paragraphs (if any) inside a segment (section or chapter) begin on new lines.
      ESFM/USFM character markers and footnotes and cross-references remain unaltered (as these have nice start/end markers), e.g., p={v3}Blessed \add be\add* the God and Father of our Lord Jesus Christ, the Father of mercies and God of all comfort;{v4}who comforteth us...

  2. JSON (deprecated)

    Found in folders ByBook.1.JSON or ByChapter.1.JSON (each folder typically around 9MB for an entire Bible) depending on the needs (and size/memory limitations) of your application or device.

    The book files are called BBB.1.json, e.g., PE1.1.json. The chapter files are called BBB_C.1.json, e.g., ACT_26.1.json, where BBB is the three-character book code from the Bible Organisational System (BOS).

    Each file contains an array of entries (lines), each containing one, two, or three entries:

    1. The first (string) entry is the BOS internal field marker, e.g., ip or s1 or v or v~. Note that BOS end markers are converted from starting with ¬ to ~, so ~v instead of ¬v. (This encodes cleaner in json files.)
    2. The second (string) entry is the contents of the field. It can be an empty string. If there’s no second entry, it’s None (or null in json).
    3. The third (array) entry if present, are the BOS extras, which include things like footnotes and cross-references. Each entry has three fields:
      1. The marker (string), e.g., f for footnotes and x for cross-references.
      2. The (integer) index of the character (starting at zero) to insert the extra field before.
      3. The (string) contents of the extra field (which may include internal USFM markers.
      e.g., "xr", 0, "- \\xo 1:13: \\xt Mat 10:2-4; Mar 3:16-19; Luk 6:14-16."

  3. Compressed HTML5 (deprecated)

    Found in folder BySection.1.CHTML (typically around 6MB for an entire Bible). But the compression dictionary is in BDCmprnDict.1.json (typically around 3KB). It consists of an array of array entries like the following:

    • [
    • "shortString",
    • "long uncompressed string of characters"
    • ],

    For example:

    • [
    • "@H",
    • "<section class=\"regularSection\"><h3 class=\"sectionHeading1\">"
    • ],

    You simply have to replace all occurrences of the first/short string with the second/long string. You should do these replacements in the order that the pairs of strings are given.

    You will also need a stylesheet. You can see a sample one here.

    You also need to load the index from BD-BCV-Index.1.json (typically around 150KB). This contains an array of array entries like the following:

    • [
    • "BBB",
    • chapterNumber of start of section,
    • verseNumber of start of section,
    • chapterNumber of end of section,
    • verseNumber of end of section,
    • file offset to compressed section,
    • length of compressed section
    • ],

    For example:

    • [
    • "GEN",
    • 2,
    • 4,
    • 2,
    • 25,
    • 7568,
    • 3550
    • ],

    Note that the .chtml files may contain newline markers after each paragraph if they were built in debug mode. (Most web browsers ignore these anyway—but they make the files slightly more human-readable.) Normally the (compressed) html is given as one big long string with no newline markers.