Documentation and structure of BibleJSON.

Converter Script

We want to make it easy to transfer to BibleJSON. Currently, we have a very buggy converter script written in Rust that converts eBible.org HTML files into BibleJSON. Soon we want to include more formats, so you can convert from USFM, USX, txt, etc.

eBible HTML files seem to be USFM just converted into HTML format, so for the div names / classes, they follow the same format as USFM.

Mass converting everything for our API

Once BibleJSON is ready we will distribute many different translations in BibleJSON via our API. We plan to make a bash script that runs our converter script through a bunch of HTML files then it outputs them in a format ready for our API. We also might do this straight in Rust, not sure yet.

Parser Package (planned)

Even with the simplifed version of USFM (below), parsing this into HTML or plain text can be a lot. We want to make an npm package (@bibleio/biblejson2html) to parse BibleJSON into html, and possibly other formats like plain text in the future.

The type names below will be the HTML classes, which you can style yourself in CSS or use our styles.

yes we’re converting html into json then the json into html, fun

BibleJSON Formatting

BibleJSON content types

USFM tag name (div class in eBible HTML)	BibleJSON type name	item type used on	Note
v	verse	content	all the content past each span.v turns into a verse object with the formatted text items, which styles are found above
ms, mt1, mt	headingBig	content
mr, mt2, s#	heading	content
d, r, sr, mt3, sp, cd, ca*, qa	headingSmall	content	like a sub header
with `ca`, it’s an alternate chapter number so the text content will be “or chapter `number`"
b, sd#	whitespace	content

BibleJSON text style types

USFM tag name (div class in eBible HTML)	BibleJSON type name	item type used on	Note
wj	red	text	Words of Jesus
p, po, cls, pmo, pm, pmc, pmr, nb, lh, lf, litl*, lik#, liv#, tr	text	text
li#, lim#	listItem	text
th#, thr#	tableColHeading	text
tc#, tcr#	tableCell	text
add, bk, sig, qt, sls, tl, it, em	italic	text
bd, bdit	bold	text
sc, nd	smallCaps	text	nd is smallCapsBold, but we combined them
qd, sup	small	text	like for notes, subtext, etc
rq, pr, qr	rightAligned	text
pc, qc, qs	centerAligned	text
pi#, mi, pb#, qm	indented	text
q#	hangingIndented	text

Structure

details
- bibleAbrv - the abbreviation of the translation that the file is, ex. “BSB”
- bibleName - the name of the translation, ex “Berean Standard Bible”
- bibleCopyright - the copyright notice of the bible translation
- bookAbrv - the short ID or abbreviation of the book that the file is, ex. “JHN”
- bookName - the name of the book, ex. “John”
- chapterNumber - the chapter number
- verseCount - the amount of verses in that file
- langEnglish - the language of the translation in English
- lang - the language
- langDir - the language direction (ltr | rtl)
content - the actual Bible content, an array
- content item objects
  - type - the type of the item - header | subheader | subHeaderReference | verse | whitespace
  - verse (only type verse ) - the verse number
  - text - array of the content
    - text item objects
      - text - the content string
      - type - the style of the item - text | indented | footnote | italic | red | smallCaps | smallCapsBold
      - footnoteText (only for footnotes) - the content of the footnote

Formatting Resources

USFM Docs - https://ubsicap.github.io/usfm/about/index.html