Unlocked Bible Interchange Format (UBXF)¶

Overview¶

The Unlocked Bible Interchange Format (UBXF) is a special type of Resource Container designed to provide a consistent format for separate apps to exchange Bible translations and metadata with one another.

Characteristics¶

The UBXF is a specific type of RC Bundle (bundle) that utilizes the USFM 3 specification to allow extra metadata to be encoded directly in the translation. All the characteristics of a RC Bundle (bundle) apply, with these added requirements:

UBXF must provide its data in USFM 3.
The format field of the manifest.yaml file must be set to text/usfm3.
Word metadata should be encoded in the translation using USFM 3 word attributes.
Alignment metadata should be encoded using USFM 3 milestones. See Alignment Data Example below.

Licensing¶

A UBXF is a derivitive work of the source and target translations in the project. It is strongly recommended that you only use texts with one of these licenses:

Public Domain
CC0
CC BY
CC BY-SA

Use the source array in the manifest.yaml file to indicate the upstream resources.

Recommended Source Texts¶

For New Testament alignment, the Unlocked Greek New Testament (UGNT) or the Bunning Heuristic Prototype (BHP) are the recommended sources.

For Old Testament alignment, the Unlocked Hebrew Bible (UHB) or the Open Scriptures Hebrew Bible (OSHB) are the recommended sources.

Alignment Data Example¶

Here is an example of alignment data encoded in UFSM 3 milestones. Note the following features:

Punctuation occurs outside the \w markers.
Alignment data must use the \zaln milestone markers. The \z prefix comes from the use of the USFM documentation of the z namespace.
Use a short code name for the actual Greek or Hebrew text that has been aligned. The example below uses the x-ugnt attribute to indicate that the UGNT text is the source. Note that the code should match what is listed in the source array in the manifest.yaml file.
The occurrence and occurrences attributes can help software identify individual occurrences of identical words within a verse.

\v 1 \zaln-s | x-strong="G39720" x-occurrence="1" x-occurrences="1" x-ugnt="Παῦλος"\*
\w Paul|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*,
\zaln-s | x-strong="G14010" x-occurrence="1" x-occurrences="1" x-ugnt="δοῦλος"\*
\w a|x-occurrence="1" x-occurrences="1"\w*
\w servant|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G23160" x-occurrence="1" x-occurrences="2" x-ugnt="Θεοῦ"\*
\w of|x-occurrence="1" x-occurrences="4"\w*
\w God|x-occurrence="1" x-occurrences="2"\w*
\zaln-e\*
\zaln-s | x-strong="G06520" x-occurrence="1" x-occurrences="1" x-ugnt="ἀπόστολος"\*
\w and|x-occurrence="1" x-occurrences="2"\w*
\w an|x-occurrence="1" x-occurrences="4"\w*
\w apostle|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G11610" x-occurrence="1" x-occurrences="1" x-ugnt="δὲ"\*
\w of|x-occurrence="2" x-occurrences="4"\w*
\zaln-e\*
\zaln-s | x-strong="G24240" x-occurrence="1" x-occurrences="1" x-ugnt="Ἰησοῦ"\*
\w Jesus|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G55470" x-occurrence="1" x-occurrences="1" x-ugnt="Χριστοῦ"\*
\w Christ|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*,
\zaln-s | x-strong="G25960" x-occurrence="1" x-occurrences="1" x-ugnt="κατὰ"\*
\w for|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G41020" x-occurrence="1" x-occurrences="1" x-ugnt="πίστιν"\*
\w the|x-occurrence="1" x-occurrences="3"\w*
\w faith|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G23160" x-occurrence="2" x-occurrences="2" x-ugnt="Θεοῦ"\*
\w of|x-occurrence="3" x-occurrences="4"\w*
\w God's|x-occurrence="2" x-occurrences="2"\w*
\zaln-e\*
\zaln-s | x-strong="G15880" x-occurrence="1" x-occurrences="1" x-ugnt="ἐκλεκτῶν"\*
\w chosen|x-occurrence="1" x-occurrences="1"\w*
\w people|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G25320" x-occurrence="1" x-occurrences="1" x-ugnt="καὶ"\*
\w and|x-occurrence="2" x-occurrences="2"\w*
\zaln-e\*
\zaln-s | x-strong="G02250" x-occurrence="1" x-occurrences="1" x-ugnt="ἀληθείας"\*
\w the|x-occurrence="2" x-occurrences="3"\w*
\zaln-e\*
\zaln-s | x-strong="G19220" x-occurrence="1" x-occurrences="1" x-ugnt="ἐπίγνωσιν"\*
\w knowledge|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G02250" x-occurrence="1" x-occurrences="1" x-ugnt="ἀληθείας"\*
\w of|x-occurrence="4" x-occurrences="4"\w*
\w truth|x-occurrence="1" x-occurrences="1"\w*
\w the|x-occurrence="3" x-occurrences="3"\w*
\zaln-e\*
\zaln-s | x-strong="G35880" x-occurrence="1" x-occurrences="1" x-ugnt="τῆς"\*
\w that|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G25960" x-occurrence="1" x-occurrences="1" x-ugnt="κατ’"\*
\w agrees|x-occurrence="1" x-occurrences="1"\w*
\w with|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\zaln-s | x-strong="G21500" x-occurrence="1" x-occurrences="1" x-ugnt="εὐσέβειαν"\*
\w godliness|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*,

Unaligned words or phrases should show up outside of the zaln milestones. For example, the English “of God” did not get aligned to “Θεοῦ” in the example below.

\v 1 \zaln-s | x-strong="G39720" x-occurrence="1" x-occurrences="1" x-ugnt="Παῦλος"\*
\w Paul|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*,
\zaln-s | x-strong="G14010" x-occurrence="1" x-occurrences="1" x-ugnt="δοῦλος"\*
\w a|x-occurrence="1" x-occurrences="1"\w*
\w servant|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*
\w of|x-occurrence="1" x-occurrences="4"\w*
\w God|x-occurrence="1" x-occurrences="2"\w*
\zaln-s | x-strong="G06520" x-occurrence="1" x-occurrences="1" x-ugnt="ἀπόστολος"\*
\w and|x-occurrence="1" x-occurrences="2"\w*
\w an|x-occurrence="1" x-occurrences="4"\w*
\w apostle|x-occurrence="1" x-occurrences="1"\w*
\zaln-e\*

Note that since the “base text” in these files is the translation (English in the example), that needs to be text complete. Missing source text (UGNT in this example) words is OK because the software should provide that text independently.