Data format

One format for every book. Code written for one collection works for the next. This is version 1, used by everything under /v1/.

How the data is shaped

collectionHisn al-Mu'min3rd ed. · 0.1.0

sections23s01 … s23

chapters149c001 … c149

entries384e0001 … e0384

source.ar.jsonArabic + structure

translations/en.jsonEnglish, by id

translations/ur.jsonnext language, same ids

bundle.jsonall of the above in one file

Divisions are the book's own sections and chapters. Entries are the adhkar, verses and remarks, in reading order. Adding a language never touches the Arabic file.

Ids

hisn-al-mumincollection:ekind: s section, c chapter, e entry0101number

Unique across all books, so several books can share one database.
Never reused. A removed entry's id is retired.
display_number is the number printed in the book: for showing, not for joining. Sort with order.

Entries

From source.ar.json, the entry for no. 97:

Loading…

Field	Type	Meaning
`id`	string	Permanent id.
`division_id`	string	The chapter the entry belongs to.
`order`	integer	Position within the chapter, from 1.
`display_number`	string or null	The number printed in the book, for display.
`type`	string	`item` a numbered dhikr or du'aa'; `quran` an unnumbered Qur'an verse; `remark` the author's note; `text` other unnumbered text.
`text`	string	The Arabic exactly as printed, with full vowels where the book has them.
`citation_raw`	string or null	The book's footnote for the entry: its sources (takhrij), grading and virtues, as printed.
`note`	string	An extra note from the book, when there is one.
`printed_pages`	integer[]	Pages of the printed edition the entry appears on.

Divisions

Divisions are one flat list. Each has a parent_id (null for a top-level section) and a level, so a book with only chapters and a book with sections and chapters use the same shape.

Loading…

Translation layers

A translation file holds only what is translated, keyed by id. A missing key means "not translated yet"; it is never an empty string.

Loading…

The file also says who or what translated it in translator, and each entry carries its own status. Division titles are under divisions.

The bundle

bundle.json merges everything into one file for simple use. Every text field becomes an object keyed by language:

Loading…

SQLite

The database holds the same data in five tables. Text keys, no row ids, ready to open read-only inside an app.

Table	Columns
`metadata`	key, value (includes the full `collection_json`)
`divisions`	id, parent_id, level, ord, title_ar
`entries`	id, division_id, ord, display_number, type, text_ar, citation_ar, note_ar, printed_pages
`division_translations`	division_id, language, title
`entry_translations`	entry_id, language, text, citation, status

-- A chapter in reading order, with English where it exists
SELECT e.display_number, e.text_ar, t.text AS text_en
FROM entries e
LEFT JOIN entry_translations t ON t.entry_id = e.id AND t.language = 'en'
WHERE e.division_id = 'hisn-al-mumin:c032'
ORDER BY e.ord;

CSV

One row per entry, UTF-8 with a byte-order mark so spreadsheet apps read the Arabic correctly. Columns: id, display_number, type, section_ar, section_en, chapter_ar, chapter_en, text_ar, text_en, citation_ar, citation_en, printed_pages.

Review status

machine

Translated by a model from the Arabic, using the style rules.

machine-retranslated

Redone after a fault, e.g. a passage cut at a page break.

reviewed

Checked against the Arabic by a person.

To show only reviewed English, filter on status == "reviewed" and fall back to the Arabic.

Versions

0.1.0published · frozen

0.1.1patch: text fixes

0.2.0minor: new fields or languages

1.0.0stable; structure changes need 2.0.0

A published version is never edited. Its address and checksums stay valid.
/v1/ is the format version. A breaking format change goes under /v2/; /v1/ stays.

Licence and credit

You canuse it in any app, site or print, including paid ones

You mustcredit Open Adhkar, and share data you derive from it under CC BY-SA

You don't have toopen-source your app's code

Credit line to use (it is also in collection.json under licence.attribution):

Open Adhkar, Hisn al-Mu'min 0.1.0 (https://openadhkar.org), CC BY-SA 4.0

The Arabic text of each book belongs to its author and is published with permission. Each collection's licence.source_text says on what terms.

Coming next

Planned as new fields, so today's code keeps working.

Recitation-only text, so audio and counter apps get just the words to say.
Repeat counts as numbers: 100, 3, 1.
Sources split up: book, hadith number and narrator as fields, with any grading credited to the scholar who gave it.
Cross-book links: the same dhikr in different books, joined by one id.
More layers: Urdu and other languages, transliteration, audio.