Qur'an text integrity
Most text software tolerates a little drift — a stray character, a normalised quote, a trimmed space. This text does not. Every letter and every mark has been fixed for centuries and is checked by people who will notice one missing dot. Your code has to treat it the way a bank treats a ledger: you can read it, index it and annotate it, but you never edit it and you can always prove which copy you shipped.
One fixed text
The Qur’an is one fixed text. It does not have editions in the sense a novel does. What varies is how the same unchanged text is transmitted (a riwayah), divided into verses (an ayah-counting system), printed (a muṣḥaf) and encoded (see encoding). None of those axes is a licence to change a letter.
That has a consequence most developers do not expect: a text that looks right is not evidence that it is right. Two copies of the same ayah can render identically and differ in bytes, and a reader cannot tell a correct verse from one with a vowel on the wrong letter unless they already know it by heart. Many of your users will.
Here is one ayah as our text dataset ships it, in the reading most of the world prints:
And the same ayah in two other readings, from the same dataset:
Three things happened there and none of them is an error: the first word is spelled differently in each reading, the
ayah is numbered 4 in one and 3 in the others, and the sukūn on the second word is a different code point in Warsh
(U+0652) from Ḥafṣ (U+06E1). A "fix-up" pass that normalised any of that would be corrupting the text.
What this asks of your code
The habits below are rules of the Qur'an text guideline; each clause links the page that owns it.
- The text is never edited in place and never generated: never edit the text (Quranic text, rule 1.2), and no normalisation on the way to storage (rule 2.2).
- Anything you add lives beside the text, addressed by position or by word number — annotations, not edits (Quranic text, rule 6.2).
- A character offset, a word position or a page coordinate belongs to one exact text: offsets name their text (Quranic text, rule 4.4).
- Recompute the digest at load and refuse to proceed on a mismatch: fail loudly (Quranic text, rule 8.4).
- Search on the form the dataset ships for it rather than one you fold yourself: the search key is derived (Quranic text, rule 6.3), and use the dataset's fold (Engineering, rule 7.1).
The cost of getting the third one wrong is measured: offsets from Quran Tajweed applied to Quran Text's words put 11 of 59 al-Fātiḥa spans on the wrong characters. Encoding shows the bytes, and Annotation layers is the pattern that avoids it.
Al-Fātiḥa is seven short ayat that every reader knows, so it is what every demo shows, and it is where encoding divergence between texts is smallest. Between Quran Text and the tajwīd edition, all seven ayat become equal after Unicode NFC; in surahs 36, 112, 113 and 114 only 40 of 98 do. A pipeline validated on surah 1 has been validated on the easy case.
What integrity does not mean
It does not mean one canonical string. Seven readings are seven different texts, each correct, each with its own letters, word count and ayah count. Integrity means each of them is the publisher’s text and nothing else, and that you always know which one you are holding. Read Riwayat for how they differ in data.
It also does not mean the datasets agree with each other byte-for-byte. Our own repositories encode the same ayah differently (one stores a shadda before its vowel, another after) and both are faithful to their sources. The join between them is a number, not a string.
How this data is made
Quran Text's seven editions are extracted from the digital packages published by the King Fahd Glorious Qurʾān Printing Complex; each muṣḥaf file names its source package and that package's SHA-256, lists every departure from it, and is rebuilt from the committed package with a build that fails if a letter moves. The tajwīd annotations are computed once over a named text edition and published with that edition's digest. See the Quran Text reference for loading and addressing the text.