USFM, OSIS, USX: Bible file formats explained
4 min read · last updated 2026-11-18
The first time you download a Bible to use in a project, it probably won’t be a nice JSON file. It’ll be USFM, or OSIS, or something called a SWORD module, and you’ll have to figure out what that is before you can do anything.
Here’s a quick tour of the formats you’re most likely to run into, and a couple of problems that trip everyone up.
USFM
USFM (Unified Standard Format Markers) is the format most Bible translation work is actually done in. It’s plain text with backslash markers:
\id JHN
\c 3
\p
\v 16 For God so loved the world that He gave His one and only Son,
that everyone who believes in Him shall not perish but have eternal life.
\id says which book it is, \c starts a chapter, \p starts a paragraph, and \v starts a verse. There are a lot more markers for headings, footnotes, cross-references, poetry and words of Jesus, but those four get you surprisingly far.
USFM is easy to read and pretty easy to parse badly. The trouble is footnotes and character styles that open and close in the middle of verses. If you’re doing anything beyond simple text, use a library instead of writing your own regexes. The project directory has some.
The spec is maintained at usfm-bible/tcdocs.
USX and USJ
USX is the same content as USFM, but in XML. USJ is the same thing again in JSON. They’re easier for programs to handle because the structure is explicit. You don’t have to guess where a footnote ends. If a source offers USX or USJ, and you’re writing code rather than editing text by hand, take those over raw USFM. The Berean Standard Bible offers both.
OSIS
OSIS (Open Scripture Information Standard) is an older XML format. It’s used by the SWORD Project and by datasets like the Open Scriptures Hebrew Bible. Verses are marked with osisID attributes like John.3.16, which is handy.
You’ll mostly run into OSIS when working with SWORD-based apps or original language data.
SWORD modules
SWORD modules are the compressed format used by AndBible, BibleTime, Xiphos and other apps built on CrossWire’s SWORD library. They aren’t meant to be read directly. If you need the text out of one, use the SWORD library itself, or a converter like BibleMultiConverter.
Everything else
You’ll also see Zefania XML, theWord and MySword files, and plenty of homemade JSON and CSV dumps. These are fine for prototypes. For homemade dumps especially, check where the text came from and what its license is. A lot of the “every translation in one JSON file” repos on GitHub include copyrighted translations nobody gave permission for.
Book codes
Every format needs a way to name books, and there are two common systems.
USFM uses three-character codes: GEN, EXO, PSA, MAT, JHN, 1CO, REV. OSIS uses short names: Gen, Exod, Ps, Matt, John, 1Cor, Rev.
Pick one for your app’s internal IDs and convert at the edges. I’d go with the USFM codes. They’re fixed-length, uppercase, and the HelloAO API uses them too.
Versification: when verse numbers don’t match
This is the one that gets everybody eventually. Not every Bible numbers its chapters and verses the same way. A few examples:
-
Hebrew Bibles count the titles of many Psalms as verse 1. So a Psalm with a title has one more verse in Hebrew than in most English Bibles, and every verse number is shifted by one.
-
Malachi has four chapters in English Bibles but three in the Hebrew Bible. English Malachi 4:1-6 is Hebrew Malachi 3:19-24.
-
Joel is the same kind of thing in reverse. English Joel 2:28-32 is Joel 3:1-5 in Hebrew, and English Joel 3 is Hebrew Joel 4.
-
The Greek Septuagint and the Latin Vulgate number most of the Psalms differently. Psalm 23 in an English Bible is Psalm 22 in those.
-
Some translations put a verse in a different place, or leave it out and keep it in a footnote. 3 John ends at verse 14 in some Bibles and verse 15 in others.
If your app shows one translation, you can mostly ignore this. If you show translations side by side, link to original language data, or store user notes by verse, you need a versification mapping. The STEPBible data has a detailed versification folder, and the SWORD project defines a set of standard versification schemes you can map between.
A tip that has saved people a lot of pain: store verse references in your database with the versification they came from, even if you only support one right now.
Parsing references people type
Last thing. Users don’t type JHN.3.16. They type “jn 3 16”, “John 3:16-18”, “1 Cor 13” or “Rom. 8:28, 31-39”. Don’t write this parser yourself unless you really want to. The Bible Passage Reference Parser (JavaScript/TypeScript) and pythonbible (Python) handle most of the mess.
Stuck on a format? Ask in Help.