Quranic Data Standards

Marqoom (مرقوم) brings together ongoing work on Quranic data standards. These docs explain the standards, the problems they address, and how projects can put them into practice.

The aim is to reduce the decisions developers have to repeat when working with Quranic data. When sources use different names, numbering conventions, and data formats, every application has to reconcile them. Shared rules and clear examples make it easier to use data across projects.

Projects using these standards

Munajjam Desktop

A desktop tool for aligning Quranic recitations with text.

AlKetab

A Quran app for reading, memorization, and review.

Quran.ws

Open datasets and tools for building Quran applications.

MP3 Quran

A library of Quran recitations by hundreds of reciters, with radio and downloads.

Why a shared standard

Say you're building an app that plays a recitation alongside the text: the recitations come from MP3 Quran and the ayah timings from Munajjam. If every project names its data its own way, you write an adapter for each one to translate its names into yours. And it doesn't stop with you: every other project writes its own adapters too, so the same work is repeated everywhere, and it grows with every project that joins.

If we agree on the names, each project learns them once and can then read everyone's data.

How many adapters does it take?

Each line in the first drawing is an adapter two projects write to read each other's data. Add a project and see how much each side grows.

Each with its own names

10 adapters

With the standard's names

5 adapters at most

This is the worst case, where every two projects exchange data. Even without it, one project reading from four sources writes four adapters. With the standard, each project needs one adapter at most, and none if it uses the names directly.

Adapters aren't the worst of it. Some differences don't fail loudly; they give you wrong data. An ayah number without its numbering system can point to a different ayah in another source. Here is what changes in one ayah record:

One ayah record, in your names and in the standard's

ayah.json+5 −4

−  "sura": 2,−  "aya": 255,+  "surah_number": 2,+  "ayah_number": 255,

One name per concept: sura and aya are other spellings of surah and ayah, and number is the number a reader cites. Reference numbers

+  "ayah_numbering_system": "kufi",

An ayah number on its own isn't enough. Al-Baqarah has 285, 286, or 287 ayahs, depending on the numbering system. Ayah counts

−  "rewaya": "Hafs",+  "riwayah": "hafs_an_asim",

Store the registry code, not display text. Hafs names a rawi; the riwayah is Hafs an Asim. Qiraat registry

−  "timing": { … }+  "ayah_timing": { … }

timing alone doesn't say whose timing it is, an ayah's or a word's. The dictionary separates ayah_timing from word_timing. Ayah timing

For now the standard settles names. Formats for text, audio, and timing are still to come, so projects may still differ in structure.

Areas of work

A standard brings together a type of content and the rules for describing and exchanging it. The documentation grows from shared terminology into connected standards built on it:

Terminology

The concepts, definitions, and naming rules the other standards build on: 73 rules and 180 concepts.

Textual data

How Quranic text and its structure are represented.

Audio data

How recitations are described, including the reciter, Riwayah, and the content of an audio file.

Segmentation and timing

How audio segments and Ayah or word timings relate to the text, including time units.