Introduction to Formats and Standards

One important factor in providing a tagged Bible translation for free use in Bible apps and programs in this modern computer age, is that the data must be readily accessible in convenient forms. Hence, Freely-Given.org has invested in designing Bible databases and file formats that themselves are offered to the Bible software world as a gift to use in whatever ways meets your needs.

Putting that a different way, the OET attempts to lead and set new directions not just in the ways the Bible text is translated and how it’s presented to the user, but also how it’s saved on computers and linked to helpful databases. And we are ‘splitters’ rather than ‘lumpers’ because we try to provide detailed information, even if it’s only discarded later.

Most existing Bible translations in the world are developed using the USFM file format. USFM includes features for marking titles and introductions, chapters and verses, section headings and paragraphs, footnotes and cross-references, and even for marking words that the translators have added, and for marking the words of Jesus (for things like red-letter Bibles). However, we want to go further to do things like:

easily annotating footnotes into classes, e.g., text-critical comments, historical comments, comments on figurative language, etc.
not just marking added words, but putting the reason they were added or changed, e.g., required by English grammar, implied by the previous sentence or context, implied by knowledge of historical context, etc.
not just marking Jesus’ words, but annotating every speech segment, including the narrator or editor.

ESFM Bible files

Enhanced Standard Format Marker (ESFM) files are based on that USFM 3 format used by most Bible translators but add the ability to include metadata (such as names of translators for that particular file) and plentiful datasets linked to each Bible word by means of associated tables.

Note that we also provide a script to convert our ESFM back to USFM (by stripping out most of the additional information).

Note also (while we’re discussing file formats for Bible software), most current Bible programs and apps weren’t designed to handle a Readers’ Version and a very Literal Version that are intended to always be used together. We have a dedicated cross-platform Bible app in early development that includes a JSON version of our ESFM files.

OET extensions

Add character fields

ESFM and USFM both have a \add character field. To that, we insert (after the space) a single character (that would not normally be expected to be part of the start of an English word) inside the added field, to indicate the reason why a word or words were added or changed in the English translation.

+ We had to add an article (like ‘a’ or ‘the’ or ‘some’) for the English to make grammatical sense
= We had to add a copula (like ‘is’) for the English to make grammatical sense
< We had to add a direct object (like ‘it’ after ‘he hit’) for the English to make grammatical sense
> We had to add an implied person or object (like ‘thing’ after ‘he took one’, or ‘person’ after ‘one’ in ‘one took the bread’) for the English to make sense
≡ We chose to repeat something that was elided (like replacing ‘pursued King A and King B’ with the longer ‘pursued King A and pursued King B’ where doing so makes the English easier to read and understand
& We had to add an owner (like replacing ‘the’ with the possessive ‘his’ in ‘raised the hands’) for the English to make sense or to be more natural (like in ‘his only son’ in John 3:16)
@ We changed a pronoun to a name (like replacing pronoun ‘he’ with the name ‘Adam’) for English fluency, or following a section heading in order to help readers who jump into the text at that point (OET-RV only)
* We changed a name to a pronoun (like replacing ‘Adam’ with the pronoun ‘he’) for English fluency
# We changed the number, mostly changing singular sayings to plural (like replacing ‘The poor man, he cries…’ with ‘Poor people, they cry…’) in order to generalise the saying for modern readers, and often to remove any wrong suggestion that it might only apply to males (OET-RV only)
^ We changed a saying to its opposite (like replacing ‘the doorway is not closed’ with ‘the door is always open’) in order to make something more natural for modern readers (OET-RV only)
≈ We reworded (single word, or phrase, or clause) (like replacing ‘said’ with ‘answered’, or replacing ‘let them go’ with ‘release them’) to make the English style more modern and easy-to-understand (OET-RV only)
Note: This is different from when this symbol is used for Hebrew parallelism (see separate section below).
? We were unable to determine what the author intended to communicate,
PLUS, if any of the above are preceded by a question-mark ‘?’, then it means that a considerable amount of doubt is involved, i.e., the intent of the original author is unclear and our best attempt might actually be wrong. (Often in those cases, we’ll simply leave the word-for-word literal text in the Readers’ Version where it’s unclear, but in some cases, even that isn’t at all understandable.)

Footnotes and cross-references

We are planning to annotate the type of all of our notes to enable some notes to be added or removed for specific online or printed OET editions. Plus we plan/hope to get specialists to write additional footnote and cross-reference sets, e.g., for a Muslim or a Jew reading this English translation, or for a specialist archeological edition, etc.

For annotating footnote types, we are currently testing the addition of a code at the beginning of the initial \ft field, e.g., ‘TC: ’ to indicate a note on textual criticism. More to come…

Hebrew parallelism

Hebrew poetry doesn't use rhyming like a lot of English poetry does, but (like English), it does often use shortish lines and often these come in pairs or doublets.

The OET-RV marks the second line of doublets with the ≈ character (commonly used in mathematics for ‘approximately equal’) to alert the reader when we consider that the author seems to be repeating a similar thought in the second line of a doublet. (This character will usually follow the space after a \q1 or \q2 field.)

For example, we might code something like:
\q1 God is my hope.
\q1 ≈Yahweh gives me comfort.

Note: This is different from when the ≈ character is used with the \add character field (see above).

Bible Books Codes

When writing any Bible software, one of the first requirements is for a list of Bible books codes . It’s common to use GEN or Gen or Gn or gen for Genesis, but what about Exodus? EXO or Exo or exo or EX or Ex or ex or EXOD or Exod or exod? The BibleOrgSys Bible books codes:

are always exactly three characters and always UPPERCASE, e.g., GEN, EXO
always start with a letter, e.g., KI1, PE2
include codes for ‘books’ beyond the sixty-six in the modern Western protestant tradition, e.g., TOB, LAO
include codes for unusual cases like SAM (which would be SA1 and SA2 (since we're no longer restricted by how big or heavy a single scroll can be—the revolutionary, new OET always considers traditions and whether or not they still need to apply)