Contributor guide
Create JSON with Gemini
Material enters the repository as one standardised JSON file per source. Gemini prepares the file using a fixed prompt; the website validates it, matches it against existing records, and an editor reviews it before anything is published. No API connection to Gemini is needed.
1. Step by step
- Choose a prompt. Use Prompt A when you have the article, chapter, fatwa or notes. Use Prompt B to ask Gemini to find a source on a question.
- Copy the prompt with the button and paste it into Gemini (gemini.google.com, AI Studio, or the Gemini app). For Prompt A, paste the source text — or attach the PDF — where the prompt says
[PASTE THE ARTICLE…]. - Send it. Gemini replies with a single JSON object. If it adds a sentence or a
```jsonfence, that is fine — the importer extracts the JSON. - Copy Gemini's whole reply and open Dashboard, Import JSON (sign-in required). Paste it, or save it as a
.jsonfile and upload it. - Validate. Errors are listed with the exact field and how to fix it. You can fix them by hand, or paste the error list back into Gemini and ask it to correct the JSON.
- Review the preview. Check the topic positions, choose matches for any scholar, book or topic flagged as a possible duplicate, and read the warnings.
- Import as draft (editors) — or submit for review (contributors). Nothing is public yet.
- Publish after review. The source then appears immediately under Supporting, Opposing or Neutral on each topic page, and every quotation, book, hadith and verse is linked to its profile.
Signed-in contributors can also generate these prompts from the import workbench, where they include the very latest topic list.
2. Topics and the three positions
Every source is classified per topic. A topic is a scholarly question with an affirmative proposition — e.g. question “Is the Witr prayer obligatory (wajib)?”, proposition “The Witr prayer is obligatory (wajib).” Positions are measured against the proposition:
- Supporting — the source's overall conclusion or reasoning supports the proposition.
- Opposing — its overall conclusion or reasoning opposes the proposition.
- Neutral — it explains, describes, gives history or surveys views without taking a side.
If the position cannot be responsibly identified, Gemini must return "unresolved". Such a source is imported as a draft and cannot be published until an editor assigns a position. Neutral is never a stand-in for uncertainty.
One source can address several topics with different positions — for example opposing “Witr is obligatory” while supporting “Witr may be one rak'ah”. Conditions and caveats go in qualifications, not in extra categories.
Topic inference. A passage often discusses a question without naming it. Gemini may then infer the topic, setting identification: "inferred" and explaining why in inference_basis. The importer checks every topic against existing titles and aliases; close-but-not-identical matches are sent to an editor rather than merged or duplicated.
Scholars vs. hadith. A hadith is recorded under its collection with its narrators. It is never stored as a “quotation” of the compiler: al-Bukhari's profile links to Sahih al-Bukhari, but the Prophet's ﷺ words and the Companions' reports are not listed as al-Bukhari's own statements. The validator rejects JSON that does this.
3. Prompt A — extract a source you already have
29,356 characters, including the current topic list
# Extract a scholarly source into Islamic Academy JSON (schema 1.1)
You are a meticulous research assistant for an academic repository of Islamic studies and jurisprudence. Read the **source material** in section 6 and convert it into ONE JSON object that follows the contract below. You only report what the source says — you cannot update any database, and an editor will review everything you return.
## 1. Rules that matter most — read first
1. **Never fabricate.** Do not invent hadith numbers, wording, narrators, gradings, page numbers, publishers, years or URLs. If the source does not state it, omit the field and, if it matters, add a `review_flags` entry saying what is missing.
2. **Absence is a finding.** When the source gives a hadith without a grading, return no `gradings` and add a review flag ("grading not stated in source") — do not supply a grade from memory.
3. **Compiler ≠ speaker.** Words inside a hadith (the Prophet's ﷺ statements, a Companion's report) are recorded in `hadiths[]` with their narrators. They are *never* a `quotes[]` entry attributed to the collection's compiler (al-Bukhari, Muslim, Abu Dawud …). A compiler appears as `contributors: [{role: "compiler"}]` on the collection in `works[]`. The compiler's *own* remarks inside his collection (al-Tirmidhi's grading comment, al-Daraqutni's critique of a chain) ARE his words: record them as a quote by the compiler (or as a grading), never by copying the hadith wording into the quote.
4. **Roles are distinct.** compiler (assembled the collection) · narrator / companion (transmitted the report) · commentator (explained it) · grader (assessed authenticity). A person can hold several roles; record each in its own place.
5. **Speaker's view vs document's use.** `quotes[].speaker_positions` = what the quoted scholar himself held; `quotes[].usage` = how THIS document uses the quote. They may differ.
6. **Exact identifiers.** Copy hadith numbers exactly as printed, and say which numbering system (`numbering_system`, e.g. "sunnah.com", "Fath al-Bari", "Abd al-Baqi"). Put other numberings in `alt_numbers`. **Never put placeholder text** ("unspecified", "n/a") in `hadith_number`: if the source gives no number, either find it in a verifiable source (e.g. sunnah.com), set `numbering_system` and add a `review_flags` entry saying the number was not in the source, or leave the report out of `hadiths[]` and keep it as a citation of the collection.
7. **Republication rights.** Write `document.summary` and paragraph blocks in your own words. Use `block_type: "excerpt"` with `is_verbatim_excerpt: true` only for short quotations. Set `document.rights.status` to "unknown" unless the source states a licence.
8. **Bibliography.** Copy each reference as printed into `original_reference`, then split what is actually present into fields. Missing metadata stays missing — the website marks the reference incomplete instead of guessing.
### Completeness, context and balance
These rules exist because earlier extractions dropped most of a fatwa's evidence, named scholars without quoting them, attributed general remarks to scholars as positions on the topic, and gave only one side of each argument. The importer rejects files that break them.
**A. Account for every reference (source_inventory).** Before writing anything else, read the whole source and list every scholar, book, hadith, Companion report, Qur'an verse, dream, historical report and claim of consensus it mentions — one `source_inventory` entry each, with the mention copied verbatim. Then make sure each entry is captured in the records (people + quotes, works + citations, hadiths, quran_verses, claims) and list those temp_ids in `recorded_as`. If something truly cannot be recorded, say why in `not_recorded_reason`. A fatwa that cites six reports and nine verses must produce six hadith/report records and nine quran_verses — not two of each.
**B. Quote scholars, do not just name them.** Whenever the source relies on a scholar's view ("Ibn Hajar endorsed it", "al-Suyuti wrote a treatise supporting it"), record that scholar's EXACT words in `quotes[]` with `quote_type: "direct"`:
- if the source quotes them, copy the quotation exactly (`origin: "source_document"`);
- if the source only names them, find the passage in the scholar's own work and record it with `origin: "research"` and a citation giving the work and the exact place (volume/page, chapter or number). Never cite a search result or a website summary as the scholar's words;
- if the words cannot be found, add a `review_flags` entry with `target` = the person's temp_id and `field: "quote"`.
Give such scholars the role `position_reported` (or `quoted`); keep `mentioned` for people named only in passing. Use `paraphrase` only when exact words are impossible, with a review flag.
**C. Give the context of every quotation (quotes[].context).** State what the scholar was actually discussing in that passage (`subject`), whether he addresses THIS question (`relevance`: `direct`, `applied` — a general statement the source applies to this question —, or `incidental`), and what kind of statement it is (`statement_type`: ruling, preference, report_of_others, passing_remark, conditional, anecdote_or_dream). Add a short `surrounding_text` excerpt when it clarifies. Example: a scholar's general statement that love of the Prophet is part of faith, used by a fatwa to justify a celebration, is `relevance: "applied"` — it is NOT that scholar's position on the celebration. `speaker_positions` is allowed only when `relevance` is `direct`. If a scholar's book is cited for one side but the scholar elsewhere criticises the practice, say so in `context.note`.
**D. Give the other side of every piece of evidence (evidence_assessments).** For each hadith, verse or quotation used as evidence for a supporting or opposing position, add at least one `evidence_assessments[]` entry from a recognised scholar who REJECTS or QUALIFIES it as evidence for this question — with `grounds` (e.g. general_not_specific, not_relevant_to_topic, weak_chain, dream_not_evidence, practice_of_salaf_absent), the scholar's exact words as a `quotes[]` entry referenced in `statement` (with its own context and citation), and any hadith/verses they cite instead in `counter_evidence`. These usually come from outside the source: mark them `origin: "research"`. Add `accepts` entries too when a scholar explicitly defends the evidence. If, after searching, no scholar disputes a piece of evidence, add a review flag with `target` = that evidence and `field: "counter_evidence"` saying so. Do not invent objections and do not put words in a scholar's mouth; precision matters more than quantity.
## 2. The three positions
Each sub-topic on which the document takes a side has a **proposition**: a plain statement such as "Witr is obligatory (wajib)." The document's position is measured against it:
- **supporting** — the document's overall conclusion or reasoning supports the sub-topic's *proposition*.
- **opposing** — the document's overall conclusion or reasoning opposes the proposition.
- **neutral** — the document explains, describes, gives history or surveys views *without* adopting either side.
- **unresolved** — you cannot responsibly tell. The editor will decide. **Never use "neutral" to mean "unsure".**
- Positions are recorded **per topic**: one document may support one proposition and oppose another.
- Keep conditions and caveats ("only when travelling", "according to the later Hanafis") in `qualifications` — do not invent extra position categories.
### Subjects and sub-topics
- Topics are **subjects, not questions**. Title them as noun phrases: "Witr prayer", and beneath it "Ruling on Witr", "Number of rak'at in Witr", "Qunut in Witr". Never title a topic as a question.
- List the broad subject (e.g. "Witr prayer") as a topic **without a position**, and each sub-topic the document addresses with `parent` set to that subject's temp_id. Sub-topic titles must make sense on their own ("Ruling on Witr", not "Ruling").
- A sub-topic on which the document takes a side needs a `proposition`; record the document's position on it. A document that only explains or surveys a subject is `neutral` on it.
- Many sources, extracted in separate runs, accumulate under the same subject. Reuse the existing subjects and sub-topics listed below; add a new sub-topic only for an issue that is genuinely not yet listed, and place it under the right parent.
- A topic may be **explicit** (the source names it) or **inferred** (the passage clearly concerns it without naming it). For inferred topics, set `identification: "inferred"` and explain why in `inference_basis`.
- Give English and transliterated forms in `aliases` / `transliterations` and index terms in `keywords` (include Arabic technical terms, e.g. "witr", "wajib", "sunnah mu'akkadah").
## 3. Repository vocabulary
Reuse these **exact** titles / names when the source refers to the same thing, so the importer links to the existing record instead of creating a duplicate. For a subject or sub-topic that already exists, copy its title and proposition verbatim and put its slug in `slug_suggestion`; list its parent subject too, with the same title.
**Existing subjects and sub-topics** (indented under their parent; slug; proposition; sources supporting / opposing / neutral):
- Witr prayer — `witr-prayer` (0 / 0 / 0)
- Number of rak'at in Witr — `witr-rakat` — measured against: "Witr may validly be prayed as a single rak'ah." (1 / 1 / 0)
- Ruling on Witr — `witr-ruling` — measured against: "Witr is obligatory (wajib)." (1 / 1 / 1)
**Hadith collections** (title — compiler — numbering system — also known as):
- Jami' al-Tirmidhi — Muhammad ibn 'Isa al-Tirmidhi — sunnah.com — جامع الترمذي; Sunan al-Tirmidhi; Tirmidhi
- Musnad Ahmad — Ahmad ibn Hanbal — sunnah.com — مسند أحمد; Musnad Ahmad ibn Hanbal; al-Musnad
- Muwatta Malik — Malik ibn Anas — sunnah.com — موطأ مالك; al-Muwatta
- Sahih Muslim — Muslim ibn al-Hajjaj al-Naysaburi — sunnah.com — صحيح مسلم; Muslim
- Sahih al-Bukhari — Muhammad ibn Isma'il al-Bukhari — sunnah.com — صحيح البخاري; al-Jami' al-Sahih; Bukhari
- Sunan Abi Dawud — Abu Dawud Sulayman ibn al-Ash'ath al-Sijistani — sunnah.com — سنن أبي داود; Sunan Abu Dawud; Abu Dawud; Abu Dawood
- Sunan Ibn Majah — Muhammad ibn Yazid Ibn Majah al-Qazwini — sunnah.com — سنن ابن ماجه; Ibn Majah
- Sunan al-Nasa'i — Ahmad ibn Shu'ayb al-Nasa'i — sunnah.com — سنن النسائي; al-Mujtaba; Nasa'i
**Scholars already in the repository:**
Abu Dawud Sulayman ibn al-Ash'ath al-Sijistani (d. 275 AH); Abu Hanifa al-Nu'man ibn Thabit (d. 150 AH); Ahmad ibn Hanbal (d. 241 AH); Ahmad ibn Shu'ayb al-Nasa'i (d. 303 AH); Burhan al-Din al-Marghinani (d. 593 AH); Malik ibn Anas (d. 179 AH); Muhammad Muhsin Khan; Muhammad ibn 'Isa al-Tirmidhi (d. 279 AH); Muhammad ibn Idris al-Shafi'i (d. 204 AH); Muhammad ibn Isma'il al-Bukhari (d. 256 AH); Muhammad ibn Yazid Ibn Majah al-Qazwini (d. 273 AH); Muslim ibn al-Hajjaj al-Naysaburi (d. 261 AH); Yahya ibn Sharaf al-Nawawi (d. 676 AH)
## 4. Field reference (generated from knowledge_import_v1.schema.json)
### `document` — object — the source being processed
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `title` | string | yes | |
| `subtitle` | string | | |
| `document_type` | "article" / "book" / "book_chapter" / "research_paper" / "fatwa" / "lecture" / "tafsir" / "hadith_commentary" / "encyclopedia_entry" / "website" / "research_notes" / "other" | yes | |
| `authors` | array of { person, role } | | Authors of THIS document (references to people[]). Items: `person`: temp_id ref; `role`: "author" | "editor" | "translator" | "compiler". |
| `publisher` | string | | |
| `publication_date` | string | | YYYY, YYYY-MM or YYYY-MM-DD exactly as known. Omit if unknown. |
| `language` | string | | ISO 639-1 code, e.g. en, ar, ur. |
| `url` | string | | |
| `doi` | string | | |
| `isbn` | string | | |
| `accessed_date` | string | | |
| `original_reference` | string | | The bibliographic reference exactly as supplied by the user / publication. |
| `summary` | string | yes | Original neutral summary written by the extractor (not copied text). |
| `keywords` | array of string | | Index keywords (English and/or transliterated Arabic terms). |
| `rights` | { status, notes } | | |
### `content_blocks` — array — structured reading text (summaries / permitted excerpts)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `order` | integer | yes | |
| `block_type` | "heading" / "paragraph" / "excerpt" / "quote" / "list" / "note" | yes | |
| `heading_level` | integer | | |
| `text` | string | yes | |
| `language` | string | | |
| `direction` | "ltr" / "rtl" | | |
| `is_verbatim_excerpt` | boolean | | true when text is copied verbatim from the source (subject to republication rights). |
### `topics` — array (≥1) — each topic + THIS document's position on it
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `title` | string | yes | Subject title as a noun phrase, never a question: "Witr prayer", "Ruling on Witr", "Number of rak'at in Witr". Sub-topic titles must make sense on their own (not just "Ruling"). |
| `slug_suggestion` | string | | |
| `question` | string | | Optional. Topics are titled as subjects; use this only to explain the issue in question form. |
| `proposition` | string | | Required when the document takes a supporting or opposing position: the statement positions are measured against, e.g. "Witr is obligatory (wajib)." Broad subjects have none. |
| `aliases` | array of string | | |
| `transliterations` | array of string | | |
| `title_arabic` | string | | |
| `category` | string | | Subject category path, e.g. "Fiqh > Prayer". |
| `subtopics` | array of string | | |
| `keywords` | array of string | | |
| `description` | string | | Neutral introductory description of the topic (not of the document). |
| `identification` | "explicit" / "inferred" | yes | explicit = the source names the topic; inferred = deduced by the extractor. |
| `inference_basis` | string | | Required when identification is inferred: why the topic was inferred. |
| `position` | "supporting" / "opposing" / "neutral" / "unresolved" | | This document's position on the topic. Omit for a parent subject that is listed only to place sub-topics in the tree. A source that only describes the subject in general is neutral. |
| `position_explanation` | string | | Why the document takes this position on this topic. |
| `qualifications` | array of string | | Conditions, exceptions and caveats the document attaches to its position. |
| `confidence` | "high" / "medium" / "low" | | |
| `parent` | temp_id ref | | temp_id of the broader subject in this file (e.g. "Ruling on Witr" → parent "Witr prayer"). List the parent subject too, without a position. |
### `people` — array — every person named (authors, scholars, narrators, graders)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `name` | string | yes | Most common scholarly transliteration, e.g. "Muhammad ibn Isma'il al-Bukhari". |
| `name_arabic` | string | | |
| `aliases` | array of string | | Other names: "Imam al-Bukhari", "al-Bukhari" … |
| `citation_name` | string | | Name as it should appear in a bibliography (e.g. "al-Nawawi, Y. ibn S."). Omit if not known. |
| `kunya` | string | | |
| `laqab` | string | | |
| `nisba` | string | | |
| `birth_year_ah` | integer | | |
| `birth_year_ce` | integer | | |
| `death_year_ah` | integer | | |
| `death_year_ce` | integer | | |
| `madhhab` | string | | |
| `person_type` | "prophet" / "companion" / "successor" / "scholar" / "narrator" / "modern_scholar" / "author" / "other" | yes | |
| `description` | string | | |
| `roles_in_document` | array of "author" / "quoted" / "compiler" / "narrator" / "grader" / "commentator" / "position_reported" / "mentioned" | | |
### `works` — array — every book / hadith collection cited
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `title` | string | yes | |
| `title_arabic` | string | | |
| `alt_titles` | array of string | | |
| `work_type` | "book" / "hadith_collection" / "tafsir" / "fiqh_manual" / "commentary" / "article" / "journal_article" / "website" / "other" | yes | |
| `contributors` | array of { person, role } | | Items: `person`: temp_id ref; `role`: "author" | "compiler" | "editor" | "translator" | "commentator" | "abridger". |
| `publisher` | string | | |
| `publication_year` | integer | | |
| `publication_place` | string | | |
| `edition` | string | | |
| `volumes` | string | | |
| `isbn` | string | | |
| `doi` | string | | |
| `url` | string | | |
| `numbering_system` | string | | Hadith collections: the numbering system used for hadith_number values (e.g. "sunnah.com", "Fath al-Bari", "Abd al-Baqi"). |
### `citations` — array — each reference as it appears in the source
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `work` | temp_id ref | | temp_id of the cited work (works[]). |
| `original_reference` | string | yes | The reference exactly as it appears in the source. |
| `volume` | string | | |
| `page` | string | | |
| `chapter` | string | | |
| `section` | string | | |
| `hadith_number` | string | | |
| `numbering_system` | string | | |
| `edition` | string | | |
| `url` | string | | |
| `block` | temp_id ref | | content_block where the citation appears. |
| `verification_status` | "unverified" / "partially_verified" / "verified" / "disputed" | | |
### `quotes` — array — scholarly quotations (NOT hadith text)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `speaker` | temp_id ref | yes | The person who SAID/WROTE the words (people[]). A hadith compiler is NOT the speaker of the hadiths he compiled — record those in hadiths[]. |
| `text` | string | yes | Quotation text (usually the English translation). |
| `text_original` | string | | |
| `original_language` | string | | |
| `translation_language` | string | | |
| `translator` | string | | |
| `quote_type` | "direct" / "paraphrase" | yes | direct = exact words. paraphrase only when the exact words cannot be found anywhere — then add a review_flag. |
| `work` | temp_id ref | | The speaker's work the words come from, when known. |
| `citation` | temp_id ref | | |
| `block` | temp_id ref | | |
| `topics` | array of temp_id ref | | |
| `speaker_positions` | array of { topic, position } | | The SPEAKER'S OWN position on a topic. Only allowed when context.relevance is "direct" — a general statement applied by the source is NOT the scholar's position on the topic. Items: `topic`: temp_id ref; `position`: "supporting" | "opposing" | "neutral" | "unresolved". |
| `usage` | array of { topic, used_for, how_used } | | How THIS DOCUMENT uses the quote (may differ from the speaker's own view). Items: `topic`: temp_id ref; `used_for`: "supporting" | "opposing" | "neutral" | "unresolved"; `how_used`: string. |
| `origin` | origin | | |
| `context` | { subject, relevance, statement_type, surrounding_text, note } | | Required in 1.1. The context in which the SCHOLAR said this — not how the source uses it. |
### `hadiths` — array — hadith references with collection + number
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `collection` | temp_id ref | yes | temp_id of a works[] entry with work_type hadith_collection. |
| `hadith_number` | string | yes | Exactly as given in the source. Never guess. |
| `numbering_system` | string | | |
| `alt_numbers` | array of { system, number } | | Items: `system`: string; `number`: string. |
| `book_name` | string | | |
| `chapter_name` | string | | |
| `narrators` | array of { person, role } | | Items: `person`: temp_id ref; `role`: "companion" | "narrator" | "transmitter". |
| `chain_text` | string | | |
| `text` | string | | Translation of the matn as quoted in the source. Never reconstruct missing wording. |
| `text_arabic` | string | | |
| `text_is_excerpt` | boolean | | |
| `gradings` | array of { grader, grade, note, citation } | | Authenticity assessments REPORTED in the source. Omit if the source gives none. Items: `grader`: temp_id ref; `grade`: string; `note`: string; `citation`: temp_id ref. |
| `cross_references` | array of { hadith } | | Items: `hadith`: temp_id ref. |
| `topics` | array of temp_id ref | | |
| `citation` | temp_id ref | | |
| `how_used` | string | | |
### `quran_verses` — array — Qur'an references (surah:ayah)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `surah` | integer | yes | |
| `ayah_start` | integer | yes | |
| `ayah_end` | integer | | |
| `arabic_text` | string | | |
| `translation` | string | | |
| `translation_source` | string | | |
| `topics` | array of temp_id ref | | |
| `citation` | temp_id ref | | |
| `how_used` | string | | |
### `claims` — array — the document's arguments and their evidence
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `topic` | temp_id ref | | |
| `statement` | string | yes | |
| `position` | "supporting" / "opposing" / "neutral" / "unresolved" | | Position relative to the topic proposition. |
| `block` | temp_id ref | | |
| `evidence` | array of { type, ref, note } | | Items: `type`: "quote" | "hadith" | "quran" | "citation" | "reasoning"; `ref`: temp_id ref; `note`: string. |
### `evidence_assessments` — array — who accepts, qualifies or rejects each piece of evidence, in their own words
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `topic` | temp_id ref | yes | The topic for which the evidence is being assessed. |
| `evidence` | temp_id ref | yes | The hadith, quran_verse, quote or claim being assessed as evidence. |
| `assessor` | temp_id ref | yes | The scholar who makes the assessment (people[]). |
| `stance` | "accepts" / "qualifies" / "rejects" | yes | accepts = valid evidence for the topic; qualifies = valid only partly / under conditions; rejects = not valid evidence for this topic. |
| `grounds` | array of "direct_text" / "analogy" / "general_not_specific" / "not_relevant_to_topic" / "different_interpretation" / "weak_chain" / "not_a_hadith" / "dream_not_evidence" / "practice_of_salaf_absent" / "contradicted_by_stronger_evidence" / "abrogated" / "other" | yes | |
| `statement` | temp_id ref | | quotes[] entry holding the assessor's EXACT words (with its own context and citation). |
| `counter_evidence` | array of temp_id ref | | hadiths[] / quran_verses[] the assessor cites against using this evidence. |
| `origin` | origin | yes | |
| `note` | string | | |
### `source_inventory` — array — EVERY reference the source makes, mapped to what you recorded
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `mention` | string | yes | How the source mentions it, copied verbatim (e.g. "Ibn Hajar", "(Bukhari)", "Remind them of the Days of God"). |
| `kind` | "scholar" / "book" / "hadith" / "athar" / "quran_verse" / "dream_or_vision" / "historical_report" / "consensus_claim" / "other" | yes | |
| `recorded_as` | array of temp_id ref | | temp_ids of the records that capture this mention (person, work, quote, hadith, quran_verse, citation, claim). |
| `not_recorded_reason` | string | | Required when recorded_as is empty: why it could not be recorded. |
### `review_flags` — array — anything uncertain an editor must check
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `target` | temp_id ref | | |
| `field` | string | | |
| `severity` | "info" / "warning" / "critical" | yes | |
| `message` | string | yes | |
## 5. Output contract — return EXACTLY one JSON object
**Output a single raw JSON object and NOTHING else.** The first character of your reply is `{` and the last is `}`. No introduction, no "Here is the JSON", no closing remarks, no markdown code fence. Caveats belong inside the JSON as `review_flags` entries. The reply is parsed by a machine; any prose outside the braces is an error.
Formatting rules:
- `schema_version` is always `"1.1"`.
- Field names must match the reference exactly — no extra fields. Omit unknown optional fields (or use null); never use empty strings.
- `temp_id`s start with a letter, use only letters/digits/_/- and are unique in the file (suggested prefixes: d, b, t, p, w, c, q, h, v, cl).
- Every reference field (`person`, `work`, `collection`, `citation`, `topics[]` …) must name a `temp_id` that exists in this same file.
- A hadith's `collection` must point to a `works[]` entry with `work_type: "hadith_collection"`.
- Arabic text goes in the `*_arabic` / `text_original` fields, unvocalised or vocalised exactly as in the source.
- Dates: YYYY, YYYY-MM or YYYY-MM-DD. URLs must be absolute (https://…).
Shape (abbreviated):
```json
{
"schema_version": "1.1",
"document": { "temp_id": "d1", "title": "…", "document_type": "fatwa", "authors": [], "publisher": "…", "url": "https://…", "summary": "Original neutral summary …", "keywords": ["…"], "rights": { "status": "unknown" } },
"content_blocks": [{ "temp_id": "b1", "order": 1, "block_type": "paragraph", "text": "…" }],
"topics": [
{ "temp_id": "t0", "title": "Witr prayer", "identification": "explicit", "keywords": ["witr"] },
{ "temp_id": "t1", "title": "Ruling on Witr", "parent": "t0", "proposition": "Witr is obligatory (wajib).", "identification": "explicit", "position": "supporting", "position_explanation": "…", "qualifications": [], "confidence": "high", "keywords": ["wajib"] }
],
"people": [
{ "temp_id": "p1", "name": "Muhammad ibn Isma'il al-Bukhari", "person_type": "scholar", "death_year_ah": 256, "roles_in_document": ["compiler"] },
{ "temp_id": "p2", "name": "…", "person_type": "companion", "roles_in_document": ["narrator"] },
{ "temp_id": "p3", "name": "…", "person_type": "scholar", "roles_in_document": ["position_reported"] },
{ "temp_id": "p4", "name": "…", "person_type": "scholar", "roles_in_document": ["mentioned"] }
],
"works": [
{ "temp_id": "w1", "title": "Sahih al-Bukhari", "work_type": "hadith_collection", "contributors": [{ "person": "p1", "role": "compiler" }], "numbering_system": "sunnah.com" },
{ "temp_id": "w2", "title": "…", "work_type": "book", "contributors": [{ "person": "p3", "role": "author" }] },
{ "temp_id": "w3", "title": "…", "work_type": "book", "contributors": [{ "person": "p4", "role": "author" }] }
],
"citations": [
{ "temp_id": "c1", "work": "w1", "original_reference": "(Bukhari)", "hadith_number": "15", "numbering_system": "sunnah.com" },
{ "temp_id": "c2", "work": "w2", "original_reference": "…", "volume": "1", "page": "123" },
{ "temp_id": "c3", "work": "w3", "original_reference": "…", "volume": "2", "page": "45" }
],
"quotes": [
{ "temp_id": "q1", "speaker": "p3", "text": "exact words …", "quote_type": "direct", "origin": "research", "work": "w2", "citation": "c2", "topics": ["t1"],
"context": { "subject": "what p3 was discussing there", "relevance": "direct", "statement_type": "ruling" },
"speaker_positions": [{ "topic": "t1", "position": "supporting" }],
"usage": [{ "topic": "t1", "used_for": "supporting", "how_used": "…" }] },
{ "temp_id": "q2", "speaker": "p4", "text": "exact words rejecting the inference …", "quote_type": "direct", "origin": "research", "work": "w3", "citation": "c3", "topics": ["t1"],
"context": { "subject": "…", "relevance": "direct", "statement_type": "ruling" } }
],
"hadiths": [{ "temp_id": "h1", "collection": "w1", "hadith_number": "15", "numbering_system": "sunnah.com", "narrators": [{ "person": "p2", "role": "companion" }], "text": "…", "text_is_excerpt": true, "topics": ["t1"], "citation": "c1", "how_used": "…" }],
"quran_verses": [{ "temp_id": "v1", "surah": 14, "ayah_start": 5, "translation": "…", "translation_source": "…", "topics": ["t1"], "how_used": "…" }],
"claims": [{ "temp_id": "cl1", "topic": "t1", "statement": "…", "position": "supporting", "evidence": [{ "type": "hadith", "ref": "h1" }, { "type": "quran", "ref": "v1" }] }],
"evidence_assessments": [
{ "temp_id": "a1", "topic": "t1", "evidence": "h1", "assessor": "p4", "stance": "rejects", "grounds": ["general_not_specific"], "statement": "q2", "counter_evidence": [], "origin": "research" }
],
"source_inventory": [
{ "mention": "(Bukhari)", "kind": "hadith", "recorded_as": ["h1", "c1"] },
{ "mention": "Remind them of the Days of God", "kind": "quran_verse", "recorded_as": ["v1"] },
{ "mention": "…named scholar…", "kind": "scholar", "recorded_as": ["p3", "q1"] }
],
"review_flags": [{ "target": "v1", "field": "counter_evidence", "severity": "info", "message": "No scholar found who disputes this verse as evidence for t1." }]
}
```
## 6. Source material
<source>
[PASTE THE ARTICLE / CHAPTER / NOTES HERE — or attach the PDF — before sending this prompt]
</source>
Reply with the raw JSON object only.4. Prompt B — research a topic with web search
Replace the bracketed question before sending. Run it several times to collect sources on each side; signed-in users get a version that lists the sources already imported so Gemini does not return them again.
29,840 characters
# Research a topic and return one source as Islamic Academy JSON (schema 1.1)
You are a meticulous research assistant with web access, working for an academic repository of Islamic studies and jurisprudence. Find **one** reliable, citable scholarly source on the subject below (a published article, book chapter, fatwa, research paper or classical text with a stable URL or full bibliographic details), read it, and convert it into ONE JSON object that follows the contract below. You only report findings — an editor reviews everything before it is published.
## 1. Research target
- **Subject:** [NAME THE SUBJECT HERE, e.g. Witr prayer, or a sub-topic such as Number of rak'at in Witr]
- **Position wanted:** any — prefer the position with the fewest sources above.
Prefer primary scholarly sources and publishers with a stable URL. Record the URL you actually opened in `document.url` — never construct a search-result URL or guess a link. If a detail (author, year, page) is not visible in the source, leave it out.
## 2. Rules that matter most — read first
1. **Never fabricate.** Do not invent hadith numbers, wording, narrators, gradings, page numbers, publishers, years or URLs. If the source does not state it, omit the field and, if it matters, add a `review_flags` entry saying what is missing.
2. **Absence is a finding.** When the source gives a hadith without a grading, return no `gradings` and add a review flag ("grading not stated in source") — do not supply a grade from memory.
3. **Compiler ≠ speaker.** Words inside a hadith (the Prophet's ﷺ statements, a Companion's report) are recorded in `hadiths[]` with their narrators. They are *never* a `quotes[]` entry attributed to the collection's compiler (al-Bukhari, Muslim, Abu Dawud …). A compiler appears as `contributors: [{role: "compiler"}]` on the collection in `works[]`. The compiler's *own* remarks inside his collection (al-Tirmidhi's grading comment, al-Daraqutni's critique of a chain) ARE his words: record them as a quote by the compiler (or as a grading), never by copying the hadith wording into the quote.
4. **Roles are distinct.** compiler (assembled the collection) · narrator / companion (transmitted the report) · commentator (explained it) · grader (assessed authenticity). A person can hold several roles; record each in its own place.
5. **Speaker's view vs document's use.** `quotes[].speaker_positions` = what the quoted scholar himself held; `quotes[].usage` = how THIS document uses the quote. They may differ.
6. **Exact identifiers.** Copy hadith numbers exactly as printed, and say which numbering system (`numbering_system`, e.g. "sunnah.com", "Fath al-Bari", "Abd al-Baqi"). Put other numberings in `alt_numbers`. **Never put placeholder text** ("unspecified", "n/a") in `hadith_number`: if the source gives no number, either find it in a verifiable source (e.g. sunnah.com), set `numbering_system` and add a `review_flags` entry saying the number was not in the source, or leave the report out of `hadiths[]` and keep it as a citation of the collection.
7. **Republication rights.** Write `document.summary` and paragraph blocks in your own words. Use `block_type: "excerpt"` with `is_verbatim_excerpt: true` only for short quotations. Set `document.rights.status` to "unknown" unless the source states a licence.
8. **Bibliography.** Copy each reference as printed into `original_reference`, then split what is actually present into fields. Missing metadata stays missing — the website marks the reference incomplete instead of guessing.
### Completeness, context and balance
These rules exist because earlier extractions dropped most of a fatwa's evidence, named scholars without quoting them, attributed general remarks to scholars as positions on the topic, and gave only one side of each argument. The importer rejects files that break them.
**A. Account for every reference (source_inventory).** Before writing anything else, read the whole source and list every scholar, book, hadith, Companion report, Qur'an verse, dream, historical report and claim of consensus it mentions — one `source_inventory` entry each, with the mention copied verbatim. Then make sure each entry is captured in the records (people + quotes, works + citations, hadiths, quran_verses, claims) and list those temp_ids in `recorded_as`. If something truly cannot be recorded, say why in `not_recorded_reason`. A fatwa that cites six reports and nine verses must produce six hadith/report records and nine quran_verses — not two of each.
**B. Quote scholars, do not just name them.** Whenever the source relies on a scholar's view ("Ibn Hajar endorsed it", "al-Suyuti wrote a treatise supporting it"), record that scholar's EXACT words in `quotes[]` with `quote_type: "direct"`:
- if the source quotes them, copy the quotation exactly (`origin: "source_document"`);
- if the source only names them, find the passage in the scholar's own work and record it with `origin: "research"` and a citation giving the work and the exact place (volume/page, chapter or number). Never cite a search result or a website summary as the scholar's words;
- if the words cannot be found, add a `review_flags` entry with `target` = the person's temp_id and `field: "quote"`.
Give such scholars the role `position_reported` (or `quoted`); keep `mentioned` for people named only in passing. Use `paraphrase` only when exact words are impossible, with a review flag.
**C. Give the context of every quotation (quotes[].context).** State what the scholar was actually discussing in that passage (`subject`), whether he addresses THIS question (`relevance`: `direct`, `applied` — a general statement the source applies to this question —, or `incidental`), and what kind of statement it is (`statement_type`: ruling, preference, report_of_others, passing_remark, conditional, anecdote_or_dream). Add a short `surrounding_text` excerpt when it clarifies. Example: a scholar's general statement that love of the Prophet is part of faith, used by a fatwa to justify a celebration, is `relevance: "applied"` — it is NOT that scholar's position on the celebration. `speaker_positions` is allowed only when `relevance` is `direct`. If a scholar's book is cited for one side but the scholar elsewhere criticises the practice, say so in `context.note`.
**D. Give the other side of every piece of evidence (evidence_assessments).** For each hadith, verse or quotation used as evidence for a supporting or opposing position, add at least one `evidence_assessments[]` entry from a recognised scholar who REJECTS or QUALIFIES it as evidence for this question — with `grounds` (e.g. general_not_specific, not_relevant_to_topic, weak_chain, dream_not_evidence, practice_of_salaf_absent), the scholar's exact words as a `quotes[]` entry referenced in `statement` (with its own context and citation), and any hadith/verses they cite instead in `counter_evidence`. These usually come from outside the source: mark them `origin: "research"`. Add `accepts` entries too when a scholar explicitly defends the evidence. If, after searching, no scholar disputes a piece of evidence, add a review flag with `target` = that evidence and `field: "counter_evidence"` saying so. Do not invent objections and do not put words in a scholar's mouth; precision matters more than quantity.
## 3. The three positions
Each sub-topic on which the document takes a side has a **proposition**: a plain statement such as "Witr is obligatory (wajib)." The document's position is measured against it:
- **supporting** — the document's overall conclusion or reasoning supports the sub-topic's *proposition*.
- **opposing** — the document's overall conclusion or reasoning opposes the proposition.
- **neutral** — the document explains, describes, gives history or surveys views *without* adopting either side.
- **unresolved** — you cannot responsibly tell. The editor will decide. **Never use "neutral" to mean "unsure".**
- Positions are recorded **per topic**: one document may support one proposition and oppose another.
- Keep conditions and caveats ("only when travelling", "according to the later Hanafis") in `qualifications` — do not invent extra position categories.
### Subjects and sub-topics
- Topics are **subjects, not questions**. Title them as noun phrases: "Witr prayer", and beneath it "Ruling on Witr", "Number of rak'at in Witr", "Qunut in Witr". Never title a topic as a question.
- List the broad subject (e.g. "Witr prayer") as a topic **without a position**, and each sub-topic the document addresses with `parent` set to that subject's temp_id. Sub-topic titles must make sense on their own ("Ruling on Witr", not "Ruling").
- A sub-topic on which the document takes a side needs a `proposition`; record the document's position on it. A document that only explains or surveys a subject is `neutral` on it.
- Many sources, extracted in separate runs, accumulate under the same subject. Reuse the existing subjects and sub-topics listed below; add a new sub-topic only for an issue that is genuinely not yet listed, and place it under the right parent.
- A topic may be **explicit** (the source names it) or **inferred** (the passage clearly concerns it without naming it). For inferred topics, set `identification: "inferred"` and explain why in `inference_basis`.
- Give English and transliterated forms in `aliases` / `transliterations` and index terms in `keywords` (include Arabic technical terms, e.g. "witr", "wajib", "sunnah mu'akkadah").
## 4. Repository vocabulary
Reuse these **exact** titles / names when the source refers to the same thing, so the importer links to the existing record instead of creating a duplicate. For a subject or sub-topic that already exists, copy its title and proposition verbatim and put its slug in `slug_suggestion`; list its parent subject too, with the same title.
**Existing subjects and sub-topics** (indented under their parent; slug; proposition; sources supporting / opposing / neutral):
- Witr prayer — `witr-prayer` (0 / 0 / 0)
- Number of rak'at in Witr — `witr-rakat` — measured against: "Witr may validly be prayed as a single rak'ah." (1 / 1 / 0)
- Ruling on Witr — `witr-ruling` — measured against: "Witr is obligatory (wajib)." (1 / 1 / 1)
**Hadith collections** (title — compiler — numbering system — also known as):
- Jami' al-Tirmidhi — Muhammad ibn 'Isa al-Tirmidhi — sunnah.com — جامع الترمذي; Sunan al-Tirmidhi; Tirmidhi
- Musnad Ahmad — Ahmad ibn Hanbal — sunnah.com — مسند أحمد; Musnad Ahmad ibn Hanbal; al-Musnad
- Muwatta Malik — Malik ibn Anas — sunnah.com — موطأ مالك; al-Muwatta
- Sahih Muslim — Muslim ibn al-Hajjaj al-Naysaburi — sunnah.com — صحيح مسلم; Muslim
- Sahih al-Bukhari — Muhammad ibn Isma'il al-Bukhari — sunnah.com — صحيح البخاري; al-Jami' al-Sahih; Bukhari
- Sunan Abi Dawud — Abu Dawud Sulayman ibn al-Ash'ath al-Sijistani — sunnah.com — سنن أبي داود; Sunan Abu Dawud; Abu Dawud; Abu Dawood
- Sunan Ibn Majah — Muhammad ibn Yazid Ibn Majah al-Qazwini — sunnah.com — سنن ابن ماجه; Ibn Majah
- Sunan al-Nasa'i — Ahmad ibn Shu'ayb al-Nasa'i — sunnah.com — سنن النسائي; al-Mujtaba; Nasa'i
**Scholars already in the repository:**
Abu Dawud Sulayman ibn al-Ash'ath al-Sijistani (d. 275 AH); Abu Hanifa al-Nu'man ibn Thabit (d. 150 AH); Ahmad ibn Hanbal (d. 241 AH); Ahmad ibn Shu'ayb al-Nasa'i (d. 303 AH); Burhan al-Din al-Marghinani (d. 593 AH); Malik ibn Anas (d. 179 AH); Muhammad Muhsin Khan; Muhammad ibn 'Isa al-Tirmidhi (d. 279 AH); Muhammad ibn Idris al-Shafi'i (d. 204 AH); Muhammad ibn Isma'il al-Bukhari (d. 256 AH); Muhammad ibn Yazid Ibn Majah al-Qazwini (d. 273 AH); Muslim ibn al-Hajjaj al-Naysaburi (d. 261 AH); Yahya ibn Sharaf al-Nawawi (d. 676 AH)
## 5. Field reference (generated from knowledge_import_v1.schema.json)
### `document` — object — the source being processed
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `title` | string | yes | |
| `subtitle` | string | | |
| `document_type` | "article" / "book" / "book_chapter" / "research_paper" / "fatwa" / "lecture" / "tafsir" / "hadith_commentary" / "encyclopedia_entry" / "website" / "research_notes" / "other" | yes | |
| `authors` | array of { person, role } | | Authors of THIS document (references to people[]). Items: `person`: temp_id ref; `role`: "author" | "editor" | "translator" | "compiler". |
| `publisher` | string | | |
| `publication_date` | string | | YYYY, YYYY-MM or YYYY-MM-DD exactly as known. Omit if unknown. |
| `language` | string | | ISO 639-1 code, e.g. en, ar, ur. |
| `url` | string | | |
| `doi` | string | | |
| `isbn` | string | | |
| `accessed_date` | string | | |
| `original_reference` | string | | The bibliographic reference exactly as supplied by the user / publication. |
| `summary` | string | yes | Original neutral summary written by the extractor (not copied text). |
| `keywords` | array of string | | Index keywords (English and/or transliterated Arabic terms). |
| `rights` | { status, notes } | | |
### `content_blocks` — array — structured reading text (summaries / permitted excerpts)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `order` | integer | yes | |
| `block_type` | "heading" / "paragraph" / "excerpt" / "quote" / "list" / "note" | yes | |
| `heading_level` | integer | | |
| `text` | string | yes | |
| `language` | string | | |
| `direction` | "ltr" / "rtl" | | |
| `is_verbatim_excerpt` | boolean | | true when text is copied verbatim from the source (subject to republication rights). |
### `topics` — array (≥1) — each topic + THIS document's position on it
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `title` | string | yes | Subject title as a noun phrase, never a question: "Witr prayer", "Ruling on Witr", "Number of rak'at in Witr". Sub-topic titles must make sense on their own (not just "Ruling"). |
| `slug_suggestion` | string | | |
| `question` | string | | Optional. Topics are titled as subjects; use this only to explain the issue in question form. |
| `proposition` | string | | Required when the document takes a supporting or opposing position: the statement positions are measured against, e.g. "Witr is obligatory (wajib)." Broad subjects have none. |
| `aliases` | array of string | | |
| `transliterations` | array of string | | |
| `title_arabic` | string | | |
| `category` | string | | Subject category path, e.g. "Fiqh > Prayer". |
| `subtopics` | array of string | | |
| `keywords` | array of string | | |
| `description` | string | | Neutral introductory description of the topic (not of the document). |
| `identification` | "explicit" / "inferred" | yes | explicit = the source names the topic; inferred = deduced by the extractor. |
| `inference_basis` | string | | Required when identification is inferred: why the topic was inferred. |
| `position` | "supporting" / "opposing" / "neutral" / "unresolved" | | This document's position on the topic. Omit for a parent subject that is listed only to place sub-topics in the tree. A source that only describes the subject in general is neutral. |
| `position_explanation` | string | | Why the document takes this position on this topic. |
| `qualifications` | array of string | | Conditions, exceptions and caveats the document attaches to its position. |
| `confidence` | "high" / "medium" / "low" | | |
| `parent` | temp_id ref | | temp_id of the broader subject in this file (e.g. "Ruling on Witr" → parent "Witr prayer"). List the parent subject too, without a position. |
### `people` — array — every person named (authors, scholars, narrators, graders)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `name` | string | yes | Most common scholarly transliteration, e.g. "Muhammad ibn Isma'il al-Bukhari". |
| `name_arabic` | string | | |
| `aliases` | array of string | | Other names: "Imam al-Bukhari", "al-Bukhari" … |
| `citation_name` | string | | Name as it should appear in a bibliography (e.g. "al-Nawawi, Y. ibn S."). Omit if not known. |
| `kunya` | string | | |
| `laqab` | string | | |
| `nisba` | string | | |
| `birth_year_ah` | integer | | |
| `birth_year_ce` | integer | | |
| `death_year_ah` | integer | | |
| `death_year_ce` | integer | | |
| `madhhab` | string | | |
| `person_type` | "prophet" / "companion" / "successor" / "scholar" / "narrator" / "modern_scholar" / "author" / "other" | yes | |
| `description` | string | | |
| `roles_in_document` | array of "author" / "quoted" / "compiler" / "narrator" / "grader" / "commentator" / "position_reported" / "mentioned" | | |
### `works` — array — every book / hadith collection cited
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `title` | string | yes | |
| `title_arabic` | string | | |
| `alt_titles` | array of string | | |
| `work_type` | "book" / "hadith_collection" / "tafsir" / "fiqh_manual" / "commentary" / "article" / "journal_article" / "website" / "other" | yes | |
| `contributors` | array of { person, role } | | Items: `person`: temp_id ref; `role`: "author" | "compiler" | "editor" | "translator" | "commentator" | "abridger". |
| `publisher` | string | | |
| `publication_year` | integer | | |
| `publication_place` | string | | |
| `edition` | string | | |
| `volumes` | string | | |
| `isbn` | string | | |
| `doi` | string | | |
| `url` | string | | |
| `numbering_system` | string | | Hadith collections: the numbering system used for hadith_number values (e.g. "sunnah.com", "Fath al-Bari", "Abd al-Baqi"). |
### `citations` — array — each reference as it appears in the source
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `work` | temp_id ref | | temp_id of the cited work (works[]). |
| `original_reference` | string | yes | The reference exactly as it appears in the source. |
| `volume` | string | | |
| `page` | string | | |
| `chapter` | string | | |
| `section` | string | | |
| `hadith_number` | string | | |
| `numbering_system` | string | | |
| `edition` | string | | |
| `url` | string | | |
| `block` | temp_id ref | | content_block where the citation appears. |
| `verification_status` | "unverified" / "partially_verified" / "verified" / "disputed" | | |
### `quotes` — array — scholarly quotations (NOT hadith text)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `speaker` | temp_id ref | yes | The person who SAID/WROTE the words (people[]). A hadith compiler is NOT the speaker of the hadiths he compiled — record those in hadiths[]. |
| `text` | string | yes | Quotation text (usually the English translation). |
| `text_original` | string | | |
| `original_language` | string | | |
| `translation_language` | string | | |
| `translator` | string | | |
| `quote_type` | "direct" / "paraphrase" | yes | direct = exact words. paraphrase only when the exact words cannot be found anywhere — then add a review_flag. |
| `work` | temp_id ref | | The speaker's work the words come from, when known. |
| `citation` | temp_id ref | | |
| `block` | temp_id ref | | |
| `topics` | array of temp_id ref | | |
| `speaker_positions` | array of { topic, position } | | The SPEAKER'S OWN position on a topic. Only allowed when context.relevance is "direct" — a general statement applied by the source is NOT the scholar's position on the topic. Items: `topic`: temp_id ref; `position`: "supporting" | "opposing" | "neutral" | "unresolved". |
| `usage` | array of { topic, used_for, how_used } | | How THIS DOCUMENT uses the quote (may differ from the speaker's own view). Items: `topic`: temp_id ref; `used_for`: "supporting" | "opposing" | "neutral" | "unresolved"; `how_used`: string. |
| `origin` | origin | | |
| `context` | { subject, relevance, statement_type, surrounding_text, note } | | Required in 1.1. The context in which the SCHOLAR said this — not how the source uses it. |
### `hadiths` — array — hadith references with collection + number
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `collection` | temp_id ref | yes | temp_id of a works[] entry with work_type hadith_collection. |
| `hadith_number` | string | yes | Exactly as given in the source. Never guess. |
| `numbering_system` | string | | |
| `alt_numbers` | array of { system, number } | | Items: `system`: string; `number`: string. |
| `book_name` | string | | |
| `chapter_name` | string | | |
| `narrators` | array of { person, role } | | Items: `person`: temp_id ref; `role`: "companion" | "narrator" | "transmitter". |
| `chain_text` | string | | |
| `text` | string | | Translation of the matn as quoted in the source. Never reconstruct missing wording. |
| `text_arabic` | string | | |
| `text_is_excerpt` | boolean | | |
| `gradings` | array of { grader, grade, note, citation } | | Authenticity assessments REPORTED in the source. Omit if the source gives none. Items: `grader`: temp_id ref; `grade`: string; `note`: string; `citation`: temp_id ref. |
| `cross_references` | array of { hadith } | | Items: `hadith`: temp_id ref. |
| `topics` | array of temp_id ref | | |
| `citation` | temp_id ref | | |
| `how_used` | string | | |
### `quran_verses` — array — Qur'an references (surah:ayah)
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `surah` | integer | yes | |
| `ayah_start` | integer | yes | |
| `ayah_end` | integer | | |
| `arabic_text` | string | | |
| `translation` | string | | |
| `translation_source` | string | | |
| `topics` | array of temp_id ref | | |
| `citation` | temp_id ref | | |
| `how_used` | string | | |
### `claims` — array — the document's arguments and their evidence
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `topic` | temp_id ref | | |
| `statement` | string | yes | |
| `position` | "supporting" / "opposing" / "neutral" / "unresolved" | | Position relative to the topic proposition. |
| `block` | temp_id ref | | |
| `evidence` | array of { type, ref, note } | | Items: `type`: "quote" | "hadith" | "quran" | "citation" | "reasoning"; `ref`: temp_id ref; `note`: string. |
### `evidence_assessments` — array — who accepts, qualifies or rejects each piece of evidence, in their own words
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `temp_id` | temp_id | yes | |
| `topic` | temp_id ref | yes | The topic for which the evidence is being assessed. |
| `evidence` | temp_id ref | yes | The hadith, quran_verse, quote or claim being assessed as evidence. |
| `assessor` | temp_id ref | yes | The scholar who makes the assessment (people[]). |
| `stance` | "accepts" / "qualifies" / "rejects" | yes | accepts = valid evidence for the topic; qualifies = valid only partly / under conditions; rejects = not valid evidence for this topic. |
| `grounds` | array of "direct_text" / "analogy" / "general_not_specific" / "not_relevant_to_topic" / "different_interpretation" / "weak_chain" / "not_a_hadith" / "dream_not_evidence" / "practice_of_salaf_absent" / "contradicted_by_stronger_evidence" / "abrogated" / "other" | yes | |
| `statement` | temp_id ref | | quotes[] entry holding the assessor's EXACT words (with its own context and citation). |
| `counter_evidence` | array of temp_id ref | | hadiths[] / quran_verses[] the assessor cites against using this evidence. |
| `origin` | origin | yes | |
| `note` | string | | |
### `source_inventory` — array — EVERY reference the source makes, mapped to what you recorded
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `mention` | string | yes | How the source mentions it, copied verbatim (e.g. "Ibn Hajar", "(Bukhari)", "Remind them of the Days of God"). |
| `kind` | "scholar" / "book" / "hadith" / "athar" / "quran_verse" / "dream_or_vision" / "historical_report" / "consensus_claim" / "other" | yes | |
| `recorded_as` | array of temp_id ref | | temp_ids of the records that capture this mention (person, work, quote, hadith, quran_verse, citation, claim). |
| `not_recorded_reason` | string | | Required when recorded_as is empty: why it could not be recorded. |
### `review_flags` — array — anything uncertain an editor must check
| Field | Type | Req. | Guidance |
|---|---|---|---|
| `target` | temp_id ref | | |
| `field` | string | | |
| `severity` | "info" / "warning" / "critical" | yes | |
| `message` | string | yes | |
## 6. Output contract — return EXACTLY one JSON object
**Output a single raw JSON object and NOTHING else.** The first character of your reply is `{` and the last is `}`. No introduction, no "Here is the JSON", no closing remarks, no markdown code fence. Caveats belong inside the JSON as `review_flags` entries. The reply is parsed by a machine; any prose outside the braces is an error.
Formatting rules:
- `schema_version` is always `"1.1"`.
- Field names must match the reference exactly — no extra fields. Omit unknown optional fields (or use null); never use empty strings.
- `temp_id`s start with a letter, use only letters/digits/_/- and are unique in the file (suggested prefixes: d, b, t, p, w, c, q, h, v, cl).
- Every reference field (`person`, `work`, `collection`, `citation`, `topics[]` …) must name a `temp_id` that exists in this same file.
- A hadith's `collection` must point to a `works[]` entry with `work_type: "hadith_collection"`.
- Arabic text goes in the `*_arabic` / `text_original` fields, unvocalised or vocalised exactly as in the source.
- Dates: YYYY, YYYY-MM or YYYY-MM-DD. URLs must be absolute (https://…).
Shape (abbreviated):
```json
{
"schema_version": "1.1",
"document": { "temp_id": "d1", "title": "…", "document_type": "fatwa", "authors": [], "publisher": "…", "url": "https://…", "summary": "Original neutral summary …", "keywords": ["…"], "rights": { "status": "unknown" } },
"content_blocks": [{ "temp_id": "b1", "order": 1, "block_type": "paragraph", "text": "…" }],
"topics": [
{ "temp_id": "t0", "title": "Witr prayer", "identification": "explicit", "keywords": ["witr"] },
{ "temp_id": "t1", "title": "Ruling on Witr", "parent": "t0", "proposition": "Witr is obligatory (wajib).", "identification": "explicit", "position": "supporting", "position_explanation": "…", "qualifications": [], "confidence": "high", "keywords": ["wajib"] }
],
"people": [
{ "temp_id": "p1", "name": "Muhammad ibn Isma'il al-Bukhari", "person_type": "scholar", "death_year_ah": 256, "roles_in_document": ["compiler"] },
{ "temp_id": "p2", "name": "…", "person_type": "companion", "roles_in_document": ["narrator"] },
{ "temp_id": "p3", "name": "…", "person_type": "scholar", "roles_in_document": ["position_reported"] },
{ "temp_id": "p4", "name": "…", "person_type": "scholar", "roles_in_document": ["mentioned"] }
],
"works": [
{ "temp_id": "w1", "title": "Sahih al-Bukhari", "work_type": "hadith_collection", "contributors": [{ "person": "p1", "role": "compiler" }], "numbering_system": "sunnah.com" },
{ "temp_id": "w2", "title": "…", "work_type": "book", "contributors": [{ "person": "p3", "role": "author" }] },
{ "temp_id": "w3", "title": "…", "work_type": "book", "contributors": [{ "person": "p4", "role": "author" }] }
],
"citations": [
{ "temp_id": "c1", "work": "w1", "original_reference": "(Bukhari)", "hadith_number": "15", "numbering_system": "sunnah.com" },
{ "temp_id": "c2", "work": "w2", "original_reference": "…", "volume": "1", "page": "123" },
{ "temp_id": "c3", "work": "w3", "original_reference": "…", "volume": "2", "page": "45" }
],
"quotes": [
{ "temp_id": "q1", "speaker": "p3", "text": "exact words …", "quote_type": "direct", "origin": "research", "work": "w2", "citation": "c2", "topics": ["t1"],
"context": { "subject": "what p3 was discussing there", "relevance": "direct", "statement_type": "ruling" },
"speaker_positions": [{ "topic": "t1", "position": "supporting" }],
"usage": [{ "topic": "t1", "used_for": "supporting", "how_used": "…" }] },
{ "temp_id": "q2", "speaker": "p4", "text": "exact words rejecting the inference …", "quote_type": "direct", "origin": "research", "work": "w3", "citation": "c3", "topics": ["t1"],
"context": { "subject": "…", "relevance": "direct", "statement_type": "ruling" } }
],
"hadiths": [{ "temp_id": "h1", "collection": "w1", "hadith_number": "15", "numbering_system": "sunnah.com", "narrators": [{ "person": "p2", "role": "companion" }], "text": "…", "text_is_excerpt": true, "topics": ["t1"], "citation": "c1", "how_used": "…" }],
"quran_verses": [{ "temp_id": "v1", "surah": 14, "ayah_start": 5, "translation": "…", "translation_source": "…", "topics": ["t1"], "how_used": "…" }],
"claims": [{ "temp_id": "cl1", "topic": "t1", "statement": "…", "position": "supporting", "evidence": [{ "type": "hadith", "ref": "h1" }, { "type": "quran", "ref": "v1" }] }],
"evidence_assessments": [
{ "temp_id": "a1", "topic": "t1", "evidence": "h1", "assessor": "p4", "stance": "rejects", "grounds": ["general_not_specific"], "statement": "q2", "counter_evidence": [], "origin": "research" }
],
"source_inventory": [
{ "mention": "(Bukhari)", "kind": "hadith", "recorded_as": ["h1", "c1"] },
{ "mention": "Remind them of the Days of God", "kind": "quran_verse", "recorded_as": ["v1"] },
{ "mention": "…named scholar…", "kind": "scholar", "recorded_as": ["p3", "q1"] }
],
"review_flags": [{ "target": "v1", "field": "counter_evidence", "severity": "info", "message": "No scholar found who disputes this verse as evidence for t1." }]
}
```
Reply with the raw JSON object only.5. Example JSON
A complete import file: two topics with different positions, an inferred topic, scholars, a paraphrased quotation, four hadith from three collections with narrators and a grading, citations with incomplete bibliography, claims and review flags.
{
"schema_version": "1.1",
"document": {
"temp_id": "d1",
"title": "Is Witr Obligatory? The Majority View and Its Evidence",
"subtitle": "Sample entry — demonstration data",
"document_type": "article",
"authors": [],
"publisher": "Islamic Academy (sample data)",
"publication_date": "2026",
"language": "en",
"summary": "A short sample article presenting the view of the Shafi'i, Maliki and Hanbali schools that the Witr prayer is an emphasised sunnah rather than an obligation, and that it may be prayed as a single rak'ah. It relies on the hadith of Talhah ibn 'Ubayd Allah limiting obligatory prayers to five, the statement of 'Ali ibn Abi Talib reported by al-Tirmidhi, and the reports of Ibn 'Umar describing Witr as one rak'ah.",
"keywords": [
"witr",
"night prayer",
"sunnah mu'akkadah",
"Shafi'i fiqh"
],
"rights": {
"status": "permitted",
"notes": "Written for the repository as demonstration content."
}
},
"content_blocks": [
{
"temp_id": "b1",
"order": 1,
"block_type": "heading",
"heading_level": 2,
"text": "The question"
},
{
"temp_id": "b2",
"order": 2,
"block_type": "paragraph",
"text": "Jurists agree that Witr is among the most strongly recommended prayers. They differ on whether it is obligatory (wajib) and on whether a single rak'ah suffices. This sample article summarises the majority position."
},
{
"temp_id": "b3",
"order": 3,
"block_type": "heading",
"heading_level": 2,
"text": "Evidence that Witr is not obligatory"
},
{
"temp_id": "b4",
"order": 4,
"block_type": "paragraph",
"text": "When a man asked the Prophet ﷺ which prayers were required of him, he named the five daily prayers and, asked whether anything else was due, answered that nothing further was required unless offered voluntarily (al-Bukhari, no. 46). 'Ali ibn Abi Talib is reported by al-Tirmidhi (no. 453) as saying that Witr is not compulsory like the prescribed prayers but was established as a sunnah."
},
{
"temp_id": "b5",
"order": 5,
"block_type": "paragraph",
"text": "Al-Nawawi reports this as the position of the Shafi'i school and the majority, noting that Abu Hanifa held Witr to be wajib."
},
{
"temp_id": "b6",
"order": 6,
"block_type": "heading",
"heading_level": 2,
"text": "Witr as one rak'ah"
},
{
"temp_id": "b7",
"order": 7,
"block_type": "paragraph",
"text": "Ibn 'Umar's reports in both Sahih collections describe the night prayer as pairs of rak'at closed by a single rak'ah, and describe Witr itself as one rak'ah at the end of the night (al-Bukhari, no. 990; Muslim, no. 752)."
}
],
"topics": [
{
"temp_id": "t0",
"title": "Witr prayer",
"slug_suggestion": "witr-prayer",
"title_arabic": "صلاة الوتر",
"aliases": [
"Witr",
"Salat al-Witr"
],
"category": "Fiqh > Prayer (Salah)",
"keywords": [
"witr",
"night prayer"
],
"description": "The Witr prayer, the odd-numbered prayer that closes the night prayer: its ruling, number of rak'at, time and manner.",
"identification": "explicit"
},
{
"temp_id": "t1",
"title": "Ruling on Witr",
"slug_suggestion": "witr-ruling",
"proposition": "Witr is obligatory (wajib).",
"aliases": [
"Is Witr wajib",
"Obligation of the Witr prayer"
],
"transliterations": [
"hukm salat al-witr"
],
"title_arabic": "حكم صلاة الوتر",
"keywords": [
"witr",
"wajib",
"sunnah mu'akkadah"
],
"description": "Sunni jurists agree that Witr is strongly emphasised. The Hanafi school classes it as wajib (necessary), a category between fard and sunnah, while the Maliki, Shafi'i and Hanbali schools class it as an emphasised sunnah.",
"identification": "explicit",
"position": "opposing",
"position_explanation": "The article concludes that Witr is an emphasised sunnah and not obligatory, citing the hadith of Talhah ibn 'Ubayd Allah and the statement of 'Ali reported by al-Tirmidhi.",
"qualifications": [
"The article stresses that Witr should not be habitually abandoned."
],
"confidence": "high",
"parent": "t0"
},
{
"temp_id": "t2",
"title": "Number of rak'at in Witr",
"slug_suggestion": "witr-rakat",
"proposition": "Witr may validly be prayed as a single rak'ah.",
"aliases": [
"Single-rak'ah Witr",
"Praying Witr as a single rak'ah"
],
"keywords": [
"witr",
"rak'ah",
"night prayer"
],
"description": "Jurists differ on the minimum number of rak'at for Witr and on whether it may be prayed as one rak'ah on its own.",
"identification": "inferred",
"inference_basis": "The final section discusses Ibn 'Umar's reports on the number of rak'at without posing the question explicitly; its conclusion clearly affirms that one rak'ah is valid.",
"position": "supporting",
"position_explanation": "The article presents the reports of Ibn 'Umar as establishing that one rak'ah is a valid Witr.",
"qualifications": [],
"confidence": "medium",
"parent": "t0"
}
],
"people": [
{
"temp_id": "p_bukhari",
"name": "Muhammad ibn Isma'il al-Bukhari",
"name_arabic": "محمد بن إسماعيل البخاري",
"aliases": [
"al-Bukhari",
"Imam al-Bukhari"
],
"death_year_ah": 256,
"death_year_ce": 870,
"person_type": "scholar",
"roles_in_document": [
"compiler"
]
},
{
"temp_id": "p_muslim",
"name": "Muslim ibn al-Hajjaj al-Naysaburi",
"aliases": [
"Imam Muslim"
],
"death_year_ah": 261,
"death_year_ce": 875,
"person_type": "scholar",
"roles_in_document": [
"compiler"
]
},
{
"temp_id": "p_tirmidhi",
"name": "Muhammad ibn 'Isa al-Tirmidhi",
"aliases": [
"al-Tirmidhi",
"Imam al-Tirmidhi"
],
"death_year_ah": 279,
"death_year_ce": 892,
"person_type": "scholar",
"roles_in_document": [
"compiler",
"grader"
]
},
{
"temp_id": "p_talhah",
"name": "Talhah ibn 'Ubayd Allah",
"aliases": [
"Talha ibn Ubaydullah"
],
"death_year_ah": 36,
"person_type": "companion",
"roles_in_document": [
"narrator"
]
},
{
"temp_id": "p_ibn_umar",
"name": "'Abd Allah ibn 'Umar",
"aliases": [
"Ibn 'Umar",
"Abdullah ibn Umar"
],
"death_year_ah": 73,
"person_type": "companion",
"roles_in_document": [
"narrator"
]
},
{
"temp_id": "p_ali",
"name": "'Ali ibn Abi Talib",
"name_arabic": "علي بن أبي طالب",
"aliases": [
"Ali ibn Abi Talib"
],
"death_year_ah": 40,
"person_type": "companion",
"roles_in_document": [
"narrator"
]
},
{
"temp_id": "p_nawawi",
"name": "Yahya ibn Sharaf al-Nawawi",
"name_arabic": "يحيى بن شرف النووي",
"aliases": [
"al-Nawawi",
"Imam al-Nawawi"
],
"death_year_ah": 676,
"death_year_ce": 1277,
"madhhab": "Shafi'i",
"person_type": "scholar",
"roles_in_document": [
"quoted"
]
},
{
"temp_id": "p_abu_hanifa",
"name": "Abu Hanifa al-Nu'man ibn Thabit",
"aliases": [
"Abu Hanifa",
"Imam Abu Hanifah"
],
"death_year_ah": 150,
"death_year_ce": 767,
"madhhab": "Hanafi",
"person_type": "scholar",
"roles_in_document": [
"position_reported"
]
},
{
"temp_id": "p_khan",
"name": "Muhammad Muhsin Khan",
"citation_name": "Khan, M. M.",
"person_type": "modern_scholar",
"roles_in_document": [
"mentioned"
]
}
],
"works": [
{
"temp_id": "w_bukhari",
"title": "Sahih al-Bukhari",
"title_arabic": "صحيح البخاري",
"alt_titles": [
"al-Jami' al-Sahih"
],
"work_type": "hadith_collection",
"contributors": [
{
"person": "p_bukhari",
"role": "compiler"
}
],
"numbering_system": "sunnah.com"
},
{
"temp_id": "w_muslim",
"title": "Sahih Muslim",
"work_type": "hadith_collection",
"contributors": [
{
"person": "p_muslim",
"role": "compiler"
}
],
"numbering_system": "sunnah.com"
},
{
"temp_id": "w_tirmidhi",
"title": "Jami' al-Tirmidhi",
"work_type": "hadith_collection",
"contributors": [
{
"person": "p_tirmidhi",
"role": "compiler"
}
],
"numbering_system": "sunnah.com"
},
{
"temp_id": "w_majmu",
"title": "al-Majmu' Sharh al-Muhadhdhab",
"title_arabic": "المجموع شرح المهذب",
"work_type": "fiqh_manual",
"contributors": [
{
"person": "p_nawawi",
"role": "author"
}
]
},
{
"temp_id": "w_khan",
"title": "The Translation of the Meanings of Sahih al-Bukhari",
"work_type": "book",
"contributors": [
{
"person": "p_bukhari",
"role": "compiler"
},
{
"person": "p_khan",
"role": "translator"
}
],
"publisher": "Darussalam",
"publication_year": 1997,
"publication_place": "Riyadh",
"volumes": "9"
}
],
"citations": [
{
"temp_id": "c1",
"work": "w_bukhari",
"original_reference": "al-Bukhari, Sahih, Kitab al-Iman, no. 46",
"chapter": "Kitab al-Iman",
"hadith_number": "46",
"numbering_system": "sunnah.com",
"block": "b4"
},
{
"temp_id": "c2",
"work": "w_bukhari",
"original_reference": "al-Bukhari, Sahih, Kitab al-Witr, no. 990",
"chapter": "Kitab al-Witr",
"hadith_number": "990",
"numbering_system": "sunnah.com",
"block": "b7"
},
{
"temp_id": "c3",
"work": "w_muslim",
"original_reference": "Muslim, Sahih, Kitab Salat al-Musafirin, no. 752",
"chapter": "Kitab Salat al-Musafirin wa Qasriha",
"hadith_number": "752",
"numbering_system": "sunnah.com",
"block": "b7"
},
{
"temp_id": "c4",
"work": "w_tirmidhi",
"original_reference": "al-Tirmidhi, Jami', Abwab al-Witr, no. 453",
"chapter": "Abwab al-Witr",
"hadith_number": "453",
"numbering_system": "sunnah.com",
"block": "b4"
},
{
"temp_id": "c5",
"work": "w_majmu",
"original_reference": "al-Nawawi, al-Majmu' Sharh al-Muhadhdhab, vol. 4",
"volume": "4",
"block": "b5"
},
{
"temp_id": "c6",
"work": "w_khan",
"original_reference": "Khan, M. M. (Trans.). (1997). The Translation of the Meanings of Sahih al-Bukhari. Darussalam."
}
],
"quotes": [
{
"temp_id": "q1",
"speaker": "p_nawawi",
"text": "Witr is a sunnah and not obligatory according to the Shafi'i school and the majority of scholars, whereas Abu Hanifa held it to be wajib.",
"quote_type": "paraphrase",
"work": "w_majmu",
"citation": "c5",
"block": "b5",
"topics": [
"t1"
],
"speaker_positions": [
{
"topic": "t1",
"position": "opposing"
}
],
"usage": [
{
"topic": "t1",
"used_for": "opposing",
"how_used": "Cited to show that denying the obligation of Witr is the position of the majority."
}
],
"origin": "source_document",
"context": {
"subject": "Al-Nawawi's discussion of the ruling on Witr in al-Majmu', where he sets out the position of the Shafi'i school and the other schools.",
"relevance": "direct",
"statement_type": "report_of_others",
"note": "He reports the school positions, including his own Shafi'i school's; the sample records this as a paraphrase, not his exact wording."
}
}
],
"hadiths": [
{
"temp_id": "h1",
"collection": "w_bukhari",
"hadith_number": "46",
"numbering_system": "sunnah.com",
"book_name": "Kitab al-Iman",
"narrators": [
{
"person": "p_talhah",
"role": "companion"
}
],
"text": "Allah's Messenger replied, 'You have to offer perfectly the five compulsory prayers in a day and night.' The man asked, 'Is there any more (praying)?' He replied, 'No, but if you want to offer the Nawafil prayers (you can).'",
"text_is_excerpt": true,
"topics": [
"t1"
],
"citation": "c1",
"how_used": "The obligatory prayers are limited to five; anything further is voluntary."
},
{
"temp_id": "h2",
"collection": "w_bukhari",
"hadith_number": "990",
"numbering_system": "sunnah.com",
"book_name": "Kitab al-Witr",
"narrators": [
{
"person": "p_ibn_umar",
"role": "companion"
}
],
"text": "The night prayer is offered as two rak'at followed by two rak'at and so on, and if anyone fears the approach of dawn, he should pray one rak'ah and this will be a Witr for all the rak'at which he has prayed before.",
"text_arabic": "صلاة الليل مثنى مثنى، فإذا خشي أحدكم الصبح صلى ركعة واحدة توتر له ما قد صلى",
"text_is_excerpt": true,
"topics": [
"t2"
],
"citation": "c2",
"how_used": "A single rak'ah closes the night prayer as Witr."
},
{
"temp_id": "h3",
"collection": "w_muslim",
"hadith_number": "752",
"numbering_system": "sunnah.com",
"book_name": "Kitab Salat al-Musafirin wa Qasriha",
"narrators": [
{
"person": "p_ibn_umar",
"role": "companion"
}
],
"text": "Witr is one rak'ah at the end of the night.",
"text_arabic": "الوتر ركعة من آخر الليل",
"text_is_excerpt": true,
"topics": [
"t2"
],
"citation": "c3",
"cross_references": [
{
"hadith": "h2"
}
]
},
{
"temp_id": "h4",
"collection": "w_tirmidhi",
"hadith_number": "453",
"numbering_system": "sunnah.com",
"book_name": "Abwab al-Witr",
"narrators": [
{
"person": "p_ali",
"role": "companion"
}
],
"text": "Witr is not compulsory like your prescribed prayers, but the Messenger of Allah ﷺ established it as a sunnah.",
"text_arabic": "الوتر ليس بحتم كصلاتكم المكتوبة، ولكن سن رسول الله صلى الله عليه وسلم",
"text_is_excerpt": true,
"gradings": [
{
"grader": "p_tirmidhi",
"grade": "hasan",
"note": "Al-Tirmidhi's comment after the report.",
"citation": "c4"
}
],
"topics": [
"t1"
],
"citation": "c4",
"how_used": "A Companion explicitly denies that Witr is obligatory like the five prayers."
}
],
"quran_verses": [],
"claims": [
{
"temp_id": "cl1",
"topic": "t1",
"statement": "The Prophet ﷺ limited the obligatory prayers to five; Witr is therefore not obligatory.",
"position": "opposing",
"block": "b4",
"evidence": [
{
"type": "hadith",
"ref": "h1"
}
]
},
{
"temp_id": "cl2",
"topic": "t1",
"statement": "'Ali ibn Abi Talib stated that Witr is not compulsory like the prescribed prayers.",
"position": "opposing",
"block": "b4",
"evidence": [
{
"type": "hadith",
"ref": "h4"
},
{
"type": "quote",
"ref": "q1",
"note": "Al-Nawawi attributes this view to the majority."
}
]
},
{
"temp_id": "cl3",
"topic": "t2",
"statement": "Witr may consist of a single rak'ah.",
"position": "supporting",
"block": "b7",
"evidence": [
{
"type": "hadith",
"ref": "h2"
},
{
"type": "hadith",
"ref": "h3"
}
]
}
],
"review_flags": [
{
"target": "h1",
"field": "text",
"severity": "info",
"message": "Sample data: English wording follows the Muhsin Khan translation (c6) as an excerpt — verify against the printed edition."
},
{
"target": "c5",
"field": "page",
"severity": "info",
"message": "Page number of al-Majmu' not stated; the reference is marked incomplete."
},
{
"target": "q1",
"field": "text",
"severity": "info",
"message": "Sample data: al-Nawawi's exact wording in al-Majmu' has not been added; the quotation is a paraphrase."
},
{
"target": "p_nawawi",
"field": "quote",
"severity": "info",
"message": "Sample data: exact quotation of al-Nawawi to be added from al-Majmu' (vol. 4)."
},
{
"target": "p_abu_hanifa",
"field": "quote",
"severity": "info",
"message": "Sample data: Abu Hanifa's position is reported, not quoted; add the wording from a Hanafi primary source."
},
{
"target": "h1",
"field": "counter_evidence",
"severity": "info",
"message": "Sample data: the Hanafi assessment of this evidence (as bearing on the obligation of Witr) has not yet been researched."
},
{
"target": "h4",
"field": "counter_evidence",
"severity": "info",
"message": "Sample data: the Hanafi assessment of this evidence (as bearing on the obligation of Witr) has not yet been researched."
},
{
"target": "q1",
"field": "counter_evidence",
"severity": "info",
"message": "Sample data: the Hanafi assessment of this evidence (as bearing on the obligation of Witr) has not yet been researched."
},
{
"target": "h2",
"field": "counter_evidence",
"severity": "info",
"message": "Sample data: the Hanafi assessment of this report (on a single-rak'ah Witr) has not yet been researched."
},
{
"target": "h3",
"field": "counter_evidence",
"severity": "info",
"message": "Sample data: the Hanafi assessment of this report (on a single-rak'ah Witr) has not yet been researched."
}
],
"evidence_assessments": [],
"source_inventory": [
{
"mention": "al-Bukhari, no. 46",
"kind": "hadith",
"recorded_as": [
"h1",
"c1"
]
},
{
"mention": "'Ali ibn Abi Talib is reported by al-Tirmidhi (no. 453)",
"kind": "hadith",
"recorded_as": [
"h4",
"c4",
"p_ali"
]
},
{
"mention": "Al-Nawawi",
"kind": "scholar",
"recorded_as": [
"p_nawawi",
"q1",
"c5"
]
},
{
"mention": "the Shafi'i school and the majority",
"kind": "consensus_claim",
"recorded_as": [
"q1"
]
},
{
"mention": "Abu Hanifa held Witr to be wajib",
"kind": "scholar",
"recorded_as": [
"p_abu_hanifa"
]
},
{
"mention": "Ibn 'Umar's reports in both Sahih collections",
"kind": "hadith",
"recorded_as": [
"h2",
"h3",
"p_ibn_umar"
]
},
{
"mention": "al-Bukhari, no. 990",
"kind": "hadith",
"recorded_as": [
"h2",
"c2"
]
},
{
"mention": "Muslim, no. 752",
"kind": "hadith",
"recorded_as": [
"h3",
"c3"
]
}
]
}
6. The JSON schema
knowledge_import_v1.schema.json (JSON Schema 2020-12) is the canonical format. Top-level records: schema_version, document, content_blocks, topics, people, works, citations, quotes, hadiths, quran_verses, claims, review_flags. Records point to each other with temporary ids (temp_id); the importer replaces them with permanent database ids.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://islamic-academy.local/schema/knowledge_import_v1.schema.json",
"title": "Islamic Academy knowledge import v1",
"description": "One JSON file describes ONE source document and everything extracted from it. Records refer to each other with temporary identifiers (temp_id) that are unique inside the file; the importer replaces them with permanent database identifiers. Version 1.1 adds source_inventory (every reference in the source accounted for), quote context/origin, and evidence_assessments (how scholars accept or reject each piece of evidence).",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"document",
"topics"
],
"properties": {
"schema_version": {
"enum": [
"1.0",
"1.1"
],
"description": "Use \"1.1\". Files declaring \"1.0\" are still accepted, but the 1.1 completeness rules are then only warnings."
},
"document": {
"$ref": "#/$defs/document"
},
"content_blocks": {
"type": "array",
"items": {
"$ref": "#/$defs/content_block"
},
"default": []
},
"topics": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/topic"
}
},
"people": {
"type": "array",
"items": {
"$ref": "#/$defs/person"
},
"default": []
},
"works": {
"type": "array",
"items": {
"$ref": "#/$defs/work"
},
"default": []
},
"citations": {
"type": "array",
"items": {
"$ref": "#/$defs/citation"
},
"default": []
},
"quotes": {
"type": "array",
"items": {
"$ref": "#/$defs/quote"
},
"default": []
},
"hadiths": {
"type": "array",
"items": {
"$ref": "#/$defs/hadith"
},
"default": []
},
"quran_verses": {
"type": "array",
"items": {
"$ref": "#/$defs/quran_verse"
},
"default": []
},
"claims": {
"type": "array",
"items": {
"$ref": "#/$defs/claim"
},
"default": []
},
"review_flags": {
"type": "array",
"items": {
"$ref": "#/$defs/review_flag"
},
"default": []
},
"source_inventory": {
"type": "array",
"items": {
"$ref": "#/$defs/source_mention"
},
"default": [],
"description": "Required in 1.1: one entry for EVERY scholar, book, hadith, report, verse, dream or other authority the source mentions, each mapped to the records created for it."
},
"evidence_assessments": {
"type": "array",
"items": {
"$ref": "#/$defs/evidence_assessment"
},
"default": [],
"description": "How named scholars accept, qualify or reject a piece of evidence AS EVIDENCE FOR A TOPIC — including the opposing side the source itself may not mention."
}
},
"$defs": {
"temp_id": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$",
"description": "Temporary identifier, unique within this file, e.g. \"p1\", \"w_bukhari\", \"h3\"."
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$",
"description": "The temp_id of another record in this file."
},
"opt_string": {
"type": [
"string",
"null"
]
},
"opt_int": {
"type": [
"integer",
"null"
]
},
"position": {
"enum": [
"supporting",
"opposing",
"neutral",
"unresolved"
],
"description": "supporting / opposing / neutral relative to the topic proposition. Use \"unresolved\" when the position cannot be responsibly identified — NEVER use neutral to express uncertainty."
},
"confidence": {
"enum": [
"high",
"medium",
"low"
]
},
"verification_status": {
"enum": [
"unverified",
"partially_verified",
"verified",
"disputed"
]
},
"document": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"title",
"document_type",
"summary"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"title": {
"type": "string",
"minLength": 1
},
"subtitle": {
"$ref": "#/$defs/opt_string"
},
"document_type": {
"enum": [
"article",
"book",
"book_chapter",
"research_paper",
"fatwa",
"lecture",
"tafsir",
"hadith_commentary",
"encyclopedia_entry",
"website",
"research_notes",
"other"
]
},
"authors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"person"
],
"properties": {
"person": {
"$ref": "#/$defs/ref"
},
"role": {
"enum": [
"author",
"editor",
"translator",
"compiler"
]
}
}
},
"description": "Authors of THIS document (references to people[])."
},
"publisher": {
"$ref": "#/$defs/opt_string"
},
"publication_date": {
"type": [
"string",
"null"
],
"pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$",
"description": "YYYY, YYYY-MM or YYYY-MM-DD exactly as known. Omit if unknown."
},
"language": {
"type": [
"string",
"null"
],
"description": "ISO 639-1 code, e.g. en, ar, ur."
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"doi": {
"$ref": "#/$defs/opt_string"
},
"isbn": {
"$ref": "#/$defs/opt_string"
},
"accessed_date": {
"type": [
"string",
"null"
],
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"original_reference": {
"$ref": "#/$defs/opt_string",
"description": "The bibliographic reference exactly as supplied by the user / publication."
},
"summary": {
"type": "string",
"minLength": 20,
"description": "Original neutral summary written by the extractor (not copied text)."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Index keywords (English and/or transliterated Arabic terms)."
},
"rights": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"enum": [
"unknown",
"permitted",
"public_domain",
"restricted"
]
},
"notes": {
"$ref": "#/$defs/opt_string"
}
}
}
}
},
"content_block": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"order",
"block_type",
"text"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"order": {
"type": "integer",
"minimum": 0
},
"block_type": {
"enum": [
"heading",
"paragraph",
"excerpt",
"quote",
"list",
"note"
]
},
"heading_level": {
"type": [
"integer",
"null"
],
"minimum": 2,
"maximum": 4
},
"text": {
"type": "string",
"minLength": 1
},
"language": {
"$ref": "#/$defs/opt_string"
},
"direction": {
"enum": [
"ltr",
"rtl"
]
},
"is_verbatim_excerpt": {
"type": "boolean",
"description": "true when text is copied verbatim from the source (subject to republication rights)."
}
}
},
"topic": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"title",
"identification"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"title": {
"type": "string",
"minLength": 3,
"description": "Subject title as a noun phrase, never a question: \"Witr prayer\", \"Ruling on Witr\", \"Number of rak'at in Witr\". Sub-topic titles must make sense on their own (not just \"Ruling\")."
},
"slug_suggestion": {
"type": [
"string",
"null"
],
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
},
"question": {
"type": [
"string",
"null"
],
"description": "Optional. Topics are titled as subjects; use this only to explain the issue in question form."
},
"proposition": {
"type": [
"string",
"null"
],
"minLength": 5,
"description": "Required when the document takes a supporting or opposing position: the statement positions are measured against, e.g. \"Witr is obligatory (wajib).\" Broad subjects have none."
},
"aliases": {
"type": "array",
"items": {
"type": "string"
}
},
"transliterations": {
"type": "array",
"items": {
"type": "string"
}
},
"title_arabic": {
"$ref": "#/$defs/opt_string"
},
"category": {
"type": [
"string",
"null"
],
"description": "Subject category path, e.g. \"Fiqh > Prayer\"."
},
"subtopics": {
"type": "array",
"items": {
"type": "string"
}
},
"keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": [
"string",
"null"
],
"description": "Neutral introductory description of the topic (not of the document)."
},
"identification": {
"enum": [
"explicit",
"inferred"
],
"description": "explicit = the source names the topic; inferred = deduced by the extractor."
},
"inference_basis": {
"type": [
"string",
"null"
],
"description": "Required when identification is inferred: why the topic was inferred."
},
"position": {
"$ref": "#/$defs/position",
"description": "This document's position on the topic. Omit for a parent subject that is listed only to place sub-topics in the tree. A source that only describes the subject in general is neutral."
},
"position_explanation": {
"type": [
"string",
"null"
],
"description": "Why the document takes this position on this topic."
},
"qualifications": {
"type": "array",
"items": {
"type": "string"
},
"description": "Conditions, exceptions and caveats the document attaches to its position."
},
"confidence": {
"$ref": "#/$defs/confidence"
},
"parent": {
"$ref": "#/$defs/ref",
"description": "temp_id of the broader subject in this file (e.g. \"Ruling on Witr\" → parent \"Witr prayer\"). List the parent subject too, without a position."
}
},
"allOf": [
{
"if": {
"properties": {
"identification": {
"const": "inferred"
}
}
},
"then": {
"required": [
"inference_basis"
],
"properties": {
"inference_basis": {
"type": "string",
"minLength": 5
}
}
}
}
]
},
"person": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"name",
"person_type"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"name": {
"type": "string",
"minLength": 2,
"description": "Most common scholarly transliteration, e.g. \"Muhammad ibn Isma'il al-Bukhari\"."
},
"name_arabic": {
"$ref": "#/$defs/opt_string"
},
"aliases": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other names: \"Imam al-Bukhari\", \"al-Bukhari\" …"
},
"citation_name": {
"type": [
"string",
"null"
],
"description": "Name as it should appear in a bibliography (e.g. \"al-Nawawi, Y. ibn S.\"). Omit if not known."
},
"kunya": {
"$ref": "#/$defs/opt_string"
},
"laqab": {
"$ref": "#/$defs/opt_string"
},
"nisba": {
"$ref": "#/$defs/opt_string"
},
"birth_year_ah": {
"$ref": "#/$defs/opt_int"
},
"birth_year_ce": {
"$ref": "#/$defs/opt_int"
},
"death_year_ah": {
"$ref": "#/$defs/opt_int"
},
"death_year_ce": {
"$ref": "#/$defs/opt_int"
},
"madhhab": {
"$ref": "#/$defs/opt_string"
},
"person_type": {
"enum": [
"prophet",
"companion",
"successor",
"scholar",
"narrator",
"modern_scholar",
"author",
"other"
]
},
"description": {
"$ref": "#/$defs/opt_string"
},
"roles_in_document": {
"type": "array",
"items": {
"enum": [
"author",
"quoted",
"compiler",
"narrator",
"grader",
"commentator",
"position_reported",
"mentioned"
]
}
}
}
},
"work": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"title",
"work_type"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"title": {
"type": "string",
"minLength": 1
},
"title_arabic": {
"$ref": "#/$defs/opt_string"
},
"alt_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"work_type": {
"enum": [
"book",
"hadith_collection",
"tafsir",
"fiqh_manual",
"commentary",
"article",
"journal_article",
"website",
"other"
]
},
"contributors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"person",
"role"
],
"properties": {
"person": {
"$ref": "#/$defs/ref"
},
"role": {
"enum": [
"author",
"compiler",
"editor",
"translator",
"commentator",
"abridger"
]
}
}
}
},
"publisher": {
"$ref": "#/$defs/opt_string"
},
"publication_year": {
"$ref": "#/$defs/opt_int"
},
"publication_place": {
"$ref": "#/$defs/opt_string"
},
"edition": {
"$ref": "#/$defs/opt_string"
},
"volumes": {
"$ref": "#/$defs/opt_string"
},
"isbn": {
"$ref": "#/$defs/opt_string"
},
"doi": {
"$ref": "#/$defs/opt_string"
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"numbering_system": {
"type": [
"string",
"null"
],
"description": "Hadith collections: the numbering system used for hadith_number values (e.g. \"sunnah.com\", \"Fath al-Bari\", \"Abd al-Baqi\")."
}
}
},
"citation": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"original_reference"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"work": {
"$ref": "#/$defs/ref",
"description": "temp_id of the cited work (works[])."
},
"original_reference": {
"type": "string",
"minLength": 1,
"description": "The reference exactly as it appears in the source."
},
"volume": {
"$ref": "#/$defs/opt_string"
},
"page": {
"$ref": "#/$defs/opt_string"
},
"chapter": {
"$ref": "#/$defs/opt_string"
},
"section": {
"$ref": "#/$defs/opt_string"
},
"hadith_number": {
"$ref": "#/$defs/opt_string"
},
"numbering_system": {
"$ref": "#/$defs/opt_string"
},
"edition": {
"$ref": "#/$defs/opt_string"
},
"url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"block": {
"$ref": "#/$defs/ref",
"description": "content_block where the citation appears."
},
"verification_status": {
"$ref": "#/$defs/verification_status"
}
}
},
"quote": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"speaker",
"text",
"quote_type"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"speaker": {
"$ref": "#/$defs/ref",
"description": "The person who SAID/WROTE the words (people[]). A hadith compiler is NOT the speaker of the hadiths he compiled — record those in hadiths[]."
},
"text": {
"type": "string",
"minLength": 3,
"description": "Quotation text (usually the English translation)."
},
"text_original": {
"$ref": "#/$defs/opt_string"
},
"original_language": {
"$ref": "#/$defs/opt_string"
},
"translation_language": {
"$ref": "#/$defs/opt_string"
},
"translator": {
"$ref": "#/$defs/opt_string"
},
"quote_type": {
"enum": [
"direct",
"paraphrase"
],
"description": "direct = exact words. paraphrase only when the exact words cannot be found anywhere — then add a review_flag."
},
"work": {
"$ref": "#/$defs/ref",
"description": "The speaker's work the words come from, when known."
},
"citation": {
"$ref": "#/$defs/ref"
},
"block": {
"$ref": "#/$defs/ref"
},
"topics": {
"type": "array",
"items": {
"$ref": "#/$defs/ref"
}
},
"speaker_positions": {
"type": "array",
"description": "The SPEAKER'S OWN position on a topic. Only allowed when context.relevance is \"direct\" — a general statement applied by the source is NOT the scholar's position on the topic.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"topic",
"position"
],
"properties": {
"topic": {
"$ref": "#/$defs/ref"
},
"position": {
"$ref": "#/$defs/position"
}
}
}
},
"usage": {
"type": "array",
"description": "How THIS DOCUMENT uses the quote (may differ from the speaker's own view).",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"topic"
],
"properties": {
"topic": {
"$ref": "#/$defs/ref"
},
"used_for": {
"$ref": "#/$defs/position"
},
"how_used": {
"$ref": "#/$defs/opt_string"
}
}
}
},
"origin": {
"$ref": "#/$defs/origin"
},
"context": {
"type": "object",
"additionalProperties": false,
"required": [
"subject",
"relevance",
"statement_type"
],
"description": "Required in 1.1. The context in which the SCHOLAR said this — not how the source uses it.",
"properties": {
"subject": {
"type": "string",
"minLength": 5,
"description": "What the scholar was actually discussing in the passage (e.g. \"the virtue of loving the Prophet, in his commentary on Bukhari's Kitab al-Iman\")."
},
"relevance": {
"enum": [
"direct",
"applied",
"incidental"
],
"description": "direct = the scholar is addressing this very topic; applied = a general statement that the SOURCE applies to this topic; incidental = a passing remark of little weight for this topic."
},
"statement_type": {
"enum": [
"ruling",
"preference",
"report_of_others",
"passing_remark",
"conditional",
"anecdote_or_dream",
"other"
],
"description": "ruling = his own considered ruling; preference = his tarjih among views; report_of_others = he is relaying someone else's view; passing_remark; conditional = valid only under stated conditions; anecdote_or_dream."
},
"surrounding_text": {
"type": [
"string",
"null"
],
"description": "Short excerpt from around the quote that shows its context."
},
"note": {
"type": [
"string",
"null"
]
}
}
}
}
},
"hadith": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"collection",
"hadith_number"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"collection": {
"$ref": "#/$defs/ref",
"description": "temp_id of a works[] entry with work_type hadith_collection."
},
"hadith_number": {
"type": "string",
"minLength": 1,
"description": "Exactly as given in the source. Never guess."
},
"numbering_system": {
"$ref": "#/$defs/opt_string"
},
"alt_numbers": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"system",
"number"
],
"properties": {
"system": {
"type": "string"
},
"number": {
"type": "string"
}
}
}
},
"book_name": {
"$ref": "#/$defs/opt_string"
},
"chapter_name": {
"$ref": "#/$defs/opt_string"
},
"narrators": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"person"
],
"properties": {
"person": {
"$ref": "#/$defs/ref"
},
"role": {
"enum": [
"companion",
"narrator",
"transmitter"
]
}
}
}
},
"chain_text": {
"$ref": "#/$defs/opt_string"
},
"text": {
"type": [
"string",
"null"
],
"description": "Translation of the matn as quoted in the source. Never reconstruct missing wording."
},
"text_arabic": {
"$ref": "#/$defs/opt_string"
},
"text_is_excerpt": {
"type": "boolean"
},
"gradings": {
"type": "array",
"description": "Authenticity assessments REPORTED in the source. Omit if the source gives none.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"grade"
],
"properties": {
"grader": {
"$ref": "#/$defs/ref"
},
"grade": {
"type": "string",
"minLength": 2,
"description": "e.g. sahih, hasan, da'if, hasan sahih, mawdu'"
},
"note": {
"$ref": "#/$defs/opt_string"
},
"citation": {
"$ref": "#/$defs/ref"
}
}
}
},
"cross_references": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"hadith"
],
"properties": {
"hadith": {
"$ref": "#/$defs/ref"
}
}
}
},
"topics": {
"type": "array",
"items": {
"$ref": "#/$defs/ref"
}
},
"citation": {
"$ref": "#/$defs/ref"
},
"how_used": {
"$ref": "#/$defs/opt_string"
}
}
},
"quran_verse": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"surah",
"ayah_start"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"surah": {
"type": "integer",
"minimum": 1,
"maximum": 114
},
"ayah_start": {
"type": "integer",
"minimum": 1
},
"ayah_end": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"arabic_text": {
"$ref": "#/$defs/opt_string"
},
"translation": {
"$ref": "#/$defs/opt_string"
},
"translation_source": {
"$ref": "#/$defs/opt_string"
},
"topics": {
"type": "array",
"items": {
"$ref": "#/$defs/ref"
}
},
"citation": {
"$ref": "#/$defs/ref"
},
"how_used": {
"$ref": "#/$defs/opt_string"
}
}
},
"claim": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"statement"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"topic": {
"$ref": "#/$defs/ref"
},
"statement": {
"type": "string",
"minLength": 5
},
"position": {
"$ref": "#/$defs/position"
},
"block": {
"$ref": "#/$defs/ref"
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"quote",
"hadith",
"quran",
"citation",
"reasoning"
]
},
"ref": {
"$ref": "#/$defs/ref"
},
"note": {
"$ref": "#/$defs/opt_string"
}
}
}
}
}
},
"review_flag": {
"type": "object",
"additionalProperties": false,
"required": [
"severity",
"message"
],
"properties": {
"target": {
"$ref": "#/$defs/ref"
},
"field": {
"$ref": "#/$defs/opt_string"
},
"severity": {
"enum": [
"info",
"warning",
"critical"
]
},
"message": {
"type": "string",
"minLength": 3
}
}
},
"origin": {
"enum": [
"source_document",
"research"
],
"description": "source_document = the words/claim appear in the source being imported; research = located by you in another work because the source only referred to it (a citation with an exact locator is then required)."
},
"source_mention": {
"type": "object",
"additionalProperties": false,
"required": [
"mention",
"kind"
],
"properties": {
"mention": {
"type": "string",
"minLength": 2,
"description": "How the source mentions it, copied verbatim (e.g. \"Ibn Hajar\", \"(Bukhari)\", \"Remind them of the Days of God\")."
},
"kind": {
"enum": [
"scholar",
"book",
"hadith",
"athar",
"quran_verse",
"dream_or_vision",
"historical_report",
"consensus_claim",
"other"
]
},
"recorded_as": {
"type": "array",
"items": {
"$ref": "#/$defs/ref"
},
"description": "temp_ids of the records that capture this mention (person, work, quote, hadith, quran_verse, citation, claim)."
},
"not_recorded_reason": {
"type": [
"string",
"null"
],
"description": "Required when recorded_as is empty: why it could not be recorded."
}
}
},
"evidence_assessment": {
"type": "object",
"additionalProperties": false,
"required": [
"temp_id",
"topic",
"evidence",
"assessor",
"stance",
"grounds",
"origin"
],
"properties": {
"temp_id": {
"$ref": "#/$defs/temp_id"
},
"topic": {
"$ref": "#/$defs/ref",
"description": "The topic for which the evidence is being assessed."
},
"evidence": {
"$ref": "#/$defs/ref",
"description": "The hadith, quran_verse, quote or claim being assessed as evidence."
},
"assessor": {
"$ref": "#/$defs/ref",
"description": "The scholar who makes the assessment (people[])."
},
"stance": {
"enum": [
"accepts",
"qualifies",
"rejects"
],
"description": "accepts = valid evidence for the topic; qualifies = valid only partly / under conditions; rejects = not valid evidence for this topic."
},
"grounds": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"direct_text",
"analogy",
"general_not_specific",
"not_relevant_to_topic",
"different_interpretation",
"weak_chain",
"not_a_hadith",
"dream_not_evidence",
"practice_of_salaf_absent",
"contradicted_by_stronger_evidence",
"abrogated",
"other"
]
}
},
"statement": {
"$ref": "#/$defs/ref",
"description": "quotes[] entry holding the assessor's EXACT words (with its own context and citation)."
},
"counter_evidence": {
"type": "array",
"items": {
"$ref": "#/$defs/ref"
},
"description": "hadiths[] / quran_verses[] the assessor cites against using this evidence."
},
"origin": {
"$ref": "#/$defs/origin"
},
"note": {
"type": [
"string",
"null"
]
}
}
}
}
}7. Fixing validation errors
| Message | What to do |
|---|---|
| Invalid JSON at line N | Usually a missing comma or an unescaped " inside text. Ask Gemini: “Your JSON is invalid at line N, return the corrected JSON only.” |
| unknown field “…” | A misspelt field name. The message suggests the correct one. |
| refers to “x”, but no record has that temp_id | Add the missing person/work/citation or fix the id. |
| attributed to … the compiler of … | Move the text to hadiths[] with its narrators. |
| Surah … has N ayahs | Check the verse reference against a mushaf. |
| Possible duplicate needs a decision | Not an error: choose the existing record or “create new” in the preview. |