Import

Upload and process Digital Bible Library (DBL) files to add Bible translations to the platform.

What Is the Digital Bible Library?

The Digital Bible Library (DBL) is the industry-standard format for distributing Bible translations digitally. DBL files are ZIP archives containing the full text of a Bible translation along with metadata about the translation, its language, styling information, and book naming conventions.

Bosca's import system parses these files and converts them into the platform's internal format, making the translation immediately available for browsing, searching, and AI integration.

What Gets Imported

When you upload a DBL file, the platform extracts and processes:

Component	What Is Extracted
Metadata	Translation name, abbreviation, description, publication information, and copyright details
Languages	ISO language codes, script information, text direction (LTR/RTL), and localized names
Books	Book names (short, long, abbreviation) in the translation's language, USFM codes, and canonical ordering
Chapters	Full Scripture text compiled from USX (Unified Scripture XML) into structured component trees
Styles	Rendering styles for verse numbers, poetry, red-letter text, paragraphs, headings, and other formatting elements
Variants	If the DBL file contains multiple text variants (e.g., standard and study editions), all variants are imported

The Import Process

Upload — Upload the DBL ZIP file through the admin interface or API. The file is validated and queued for processing.
Parsing — The Bible compiler extracts the metadata XML, styles XML, and all USX content files from the archive.
Compilation — USX content is compiled into Bosca's component tree format. The compiler handles chapters, verses, paragraphs, poetry, lists, tables, footnotes, cross-references, and special formatting markers.
Storage — The compiled Bible is stored as a metadata item within a collection, with all books, chapters, and component trees persisted to the database.
Publishing — The imported Bible is set to the published state, making it immediately available for browsing and API access.

The import process handles the full complexity of USX formatting — including poetry indentation levels, embedded footnotes, cross-reference markers, word-of-Christ (red-letter) indicators, and section headings. Nothing is lost in the conversion.

About USX

USX (Unified Scripture XML) is the XML-based format used inside DBL archives to encode Scripture text. It uses USFM markers (Unified Standard Format Markers) to identify structural elements like chapters, verses, paragraphs, and formatting. Bosca's Bible compiler includes an ANTLR-based parser that handles the full USX grammar.

After Import

Once imported, the Bible translation is:

Browsable through the books and chapters navigation
Searchable via human-readable references
Available to AI agents for Scripture lookup and reasoning
Embeddable in documents via the rich text editor's Bible reference node
Queryable through the GraphQL and REST APIs

The platform caches Bible content at multiple levels for fast access. Frequently requested books and chapters are served from cache rather than the database, with automatic cache invalidation when a Bible is updated.