quran-json的JSON结构完全解析:manifest、chapters与text三层数据模型

原创2026-11-13 14:13:081,995 阅读

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

三层如何配合:一次请求的完整路径

  1. GET manifest.json → 拿到书体清单、指针和版权信息;
  2. GET chapters.json → 渲染章节目录(名称、节数、麦加/麦地那);
  3. 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 结构:

  1. manifest.json 是地图——scripts、translations、audio 全是指针,先读它;
  2. chapters.json 是目录——114 章元数据只存一份,total_verses 决定每章的节号上界;
  3. text 层是内容——id 从 1 连续编号到 total_verses,number_in_hafs 让不同诵读体系也能精确互相对齐。

按"manifest → chapters → text"的顺序读一遍,再对照 schemas/ 下的四份 JSON Schema,你就能自信地在任何客户端里使用这套 Quran JSON 数据了。

登录后查看全文
quran-json