quran-json的JSON结构完全解析:manifest、chapters与text三层数据模型
quran-json的JSON结构完全解析:manifest、chapters与text三层数据模型
quran-json 是一个开源的 Quran(古兰经)JSON 数据集项目:它以纯 JSON 文件的形式发布阿拉伯原文、90 种语言的译本、转写与音频索引,全部由 Python 构建管线生成。理解它的 JSON 结构,关键是抓住 manifest、chapters、text 三层数据模型:manifest 是数据地图,chapters 是 114 章的共享元数据,text 才是真正的经文内容。本文带你快速看懂每一层的字段与相互关系。📖
三层数据模型全景图
整个数据集围绕"发现 → 元数据 → 内容"组织,客户端永远从 manifest.json 开始:
| 层级 | 文件 | 作用 | 本地快照 |
|---|---|---|---|
| ① 发现层 | manifest.json |
数据地图:有哪些脚本、译本、音频,指针指向哪里 | 由 src/quranjson/cdn.py 生成 |
| ② 元数据层 | chapters.json |
114 章的名称、类型、节数 | data/tanzil/chapters.json |
| ③ 内容层 | text/{script}/quran.json、text/{script}/chapters/{1-114}.json |
经文章节文本,按 12 种书体(script)发布 | data/quran.json、data/tanzil/ |
这种分层的最大好处:元数据只存一份,文本按需取一章,不用为了读一章下载整本 1.7 MB 语料。
第一层:manifest.json —— 数据集的"总地图"
manifest.json 是唯一入口,它的字段由 schemas/manifest.schema.json 严格约束。精简后的结构如下:
{
"chapters": { "count": 114, "path": "/chapters.json" },
"scripts": [
{
"id": "uthmani",
"name": "Uthmani",
"description": "Uthmanic orthography, full vocalisation",
"verses": 6236,
"verse_ids": "hafs",
"path": "/text/uthmani/quran.json",
"chapters": "/text/uthmani/chapters/{1-114}.json"
}
],
"translations": { "count": 90, "languages": 40, "index": "/translations/index.json" },
"transliteration": { "count": 0, "index": "/transliteration/index.json" },
"audio": "/audio/reciters.json",
"license": { "project": "CC BY-SA 4.0", "text": { "status": "granted", "…": "…" } },
"attribution": "Quran text and chapter metadata: Tanzil.net (CC-BY 3.0) …"
}
重点字段速查表:
| 字段 | 类型 | 含义 |
|---|---|---|
chapters.count / chapters.path |
int / str | 固定 114 章,指向元数据文件 |
scripts[].id |
str | 书体标识,如 uthmani、simple-clean、warsh、indopak |
scripts[].verses |
int | 该书体的总节数(Hafs 系为 6,236,Warsh/Qalun 为 6,214) |
scripts[].verse_ids |
enum | hafs / mapped / own,说明节号体系 |
scripts[].path |
str | 整本文件的 URL 路径 |
scripts[].chapters |
str | 单章文件的 URL 模板({1-114}) |
translations / transliteration |
obj | 目录指针,细节在各自的 index.json |
license / attribution |
obj / str | 版权状态与致谢,数据可追溯 |
💡 小技巧:verse_ids 告诉你节号是否可以直接和 Hafs 体系对齐。warsh、qalun、duri 是 mapped——它们的每一节自带 number_in_hafs 映射字段,跨体系关联靠查表而不是算术。
第二层:chapters.json —— 114 章的共享元数据
chapters.json 是一个 114 个对象的数组(由 schemas/chapters.schema.json 校验),以第 2 章为例:
{
"id": 2,
"name": "البقرة",
"transliteration": "Al-Baqara",
"translation": "The Cow",
"type": "medinan",
"total_verses": 286
}
| 字段 | 含义 |
|---|---|
id |
章节号 1–114 |
name |
阿拉伯语章名 |
transliteration |
罗马转写名 |
translation |
英文章名 |
type |
meccan(麦加章)或 medinan(麦地那章) |
total_verses |
该章节数 |
为什么单独抽一层?因为阿拉伯章名和节数不随书体、语言变化。如果把它们复制进每个章节文件,同样的 89 KB 要在约 10,000 个文件里重复一遍——这正是 src/quranjson/cdn.py 里 chapter_metadata() 的设计出发点。多语言章名(中文、法文等)则以每语言一份快照的形式保存在 data/chapters/ 下,例如 data/chapters/zh.json。
第三层:text 层 —— 12 种书体的章节文件
每个书体发布两种文件,二选一即可:
text/{script}/quran.json:整本,114 章的数组;text/{script}/chapters/{1-114}.json:单章对象。
单章文件的统一形状(以 Uthmani 第 1 章为例):
{
"id": 1,
"verses": [
{ "id": 1, "text": "بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِيمِ" },
{ "id": 2, "text": "ٱلۡحَمۡدُ لِلَّهِ رَبِّ ٱلۡعَٰلَمِينَ" }
]
}
规则很简单:verses[].id 恒为 1..total_verses 连续编号,text 是 UTF-8 阿拉伯文。
映射书体多一个字段。 warsh、qalun、duri 的节里带 number_in_hafs,声明它对应 Hafs 体系的哪几节(见 data/quranpedia/warsh.json):
{ "id": 1, "text": "اِ۬لْحَمْدُ لِلهِ رَبِّ اِ۬لْعَٰلَمِينَ", "number_in_hafs": [1, 2] }
这就是为什么它们只有 6,214 节却能和 Hafs 的 6,236 节无损对账——Ayat al-Kursi(2:255)在 Warsh 体系里被拆成两节,映射字段会明确标出来。更多细节见 schemas/script.schema.json。
译本复用同一形状。 translations/{code}-{slug}/chapters/{1-114}.json 中,每节是 { "id": 1, "translation": "…" }(可含 footnotes),由 schemas/translation.schema.json 约束。中文译本快照在 data/editions/zh.json,英文公共领域经典在 data/extra/。因为阿拉伯文各书体一致,译本只存译文不存原文,按 id 与 text 层拼接即可:
const [arabic, zh] = await Promise.all([
fetch("/text/simple-clean/chapters/2.json").then(r => r.json()),
fetch("/translations/zh-suliman/chapters/2.json").then(r => r.json()),
]);
// arabic.verses[i].text ↔ zh.verses[i].translation
三层如何配合:一次请求的完整路径
- GET
manifest.json→ 拿到书体清单、指针和版权信息; - GET
chapters.json→ 渲染章节目录(名称、节数、麦加/麦地那); - GET
text/{script}/chapters/1.json→ 取第 1 章正文,按id对齐译本与音频。
音频同样是 URL 模板 + 连续 id 的配合:595 部吟诵的模板在 audio/reciters.json 里声明,每部带 indexing_mode、surah_pad、ayah_pad,客户端用 id 拼出文件地址即可。
数据质量与溯源在哪看
- data/meta/sources.json:132 条快照记录,每条含
path、url、source、license裁决,说明每个字节从哪来; - data/meta/qa.json:对上游转录错误的修正记录;
- 构建管线在写入前会校验 114 章完整性、节数一致性(Hafs 系 6,236 等)与
1..n连续编号,任何一条不满足都会让构建失败,而不是发出残缺数据。
小结
📌 记住这三句话,就掌握了 quran-json 的 JSON 结构:
- manifest.json 是地图——
scripts、translations、audio全是指针,先读它; - chapters.json 是目录——114 章元数据只存一份,
total_verses决定每章的节号上界; - text 层是内容——
id从 1 连续编号到total_verses,number_in_hafs让不同诵读体系也能精确互相对齐。
按"manifest → chapters → text"的顺序读一遍,再对照 schemas/ 下的四份 JSON Schema,你就能自信地在任何客户端里使用这套 Quran JSON 数据了。