Quranic vocabulary naming standard

This standard sets the naming rules for concepts used in Quranic software. First define the concept, its meaning and its boundaries; then choose its name and derive its spelling using these rules. Record the resulting names in the terminology dictionary.

The standard names concepts that cannot be defined without reference to the Quran or mushaf. Users, subscriptions, files and other general application concepts remain outside its dictionary. The software naming guidance here applies when using its vocabulary.

The provisions of this standard are conformance requirements unless identified as recommendations or permitted options. “Must” indicates a requirement, “should” a recommendation, and “may” permission. Definitions explain meanings; examples illustrate the requirements.

The underlying idea follows convention over configuration:

Once developers know the standard's rules, they can predict concept, relationship and field names and how to use them without consulting the documentation every time.

The rules at a glance

Every rule of the standard in one table, in order. Each summary is the rule's first sentence; select a rule to read it in full with its examples.

Define the concept before naming it

Define the concept first, then choose its name.

Before adopting a term, establish:

• What does it represent?
• What are its boundaries?
• What does it exclude?
• Does it differ from a neighbouring concept?
• Why does software need to model it?

Then choose the most suitable name using the following rules.

One canonical name per concept

001. One code name per concept

After defining a concept, choose one code name for it according to this standard and record it in the dictionary. Use the same vocabulary wherever the standard applies, as far as possible.

Examples

Translation and compound names

002. Transliterating specialised terms

Retain an Arabic term when it denotes a concept specific to the Quran or its sciences, and write it in Latin letters using the spelling rules. Decide from the concept’s meaning and domain, regardless of whether an English equivalent exists.

Examples

003. Translating general concepts

Use the established technical English name for a general concept, even in a Quranic application. Having an Arabic word does not make it a specialised Quranic term; if the English equivalent is unclear, review the concept’s definition before choosing its name.

Examples

004. Forming compound names

In a compound name, transliterate the complete term originating in the Quran or its sciences, and translate the general words added to it into English. Whether a word is translated or transliterated depends on its meaning within the term.

Examples

The form for «المِيم الصَّغِيرَة» is small_meem, not meem_saghirah.

005. Order of translated adjectives

An adjective translated into English precedes the noun it describes.

Examples

006. Order of translated head nouns

A translated general head noun goes at the end of the English construction. Reverse the order of successive translated head nouns.

Examples

007. Technical meaning within a compound

This rule applies rule 004; it is not an exception. A word’s technical meaning within the compound determines its spelling: translate «إملائية» with «علامة», but transliterate it with «رسم». Its separate number is retained to make this example easy to reference.

Examples

Canonical code spelling

After choosing an Arabic term, determine how to write it in code. This form is its Canonical Code Spelling. Derive it from vocalised Arabic using the following rules so that developers arrive at the same spelling rather than each project choosing its own.

The aim is a simple, stable and predictable spelling rather than a precise scholarly rendering of pronunciation. Use ASCII without scholarly transliteration marks. Two Arabic letters may share one Latin equivalent, such as س and ص, both written s. Keep the original Arabic separately because the code spelling alone cannot reconstruct it.

The project's shared tools can check spellings. The contribution instructions explain how to check names before proposing a change.

Spelling: name format

008. Code-name format

Write the canonical code name in lowercase Latin letters, separating words in a compound with underscores: snake_case.

Examples

Spelling: consonants and vowels

009. Characters in code spelling

Write code names using ASCII, without scholarly transliteration marks or an apostrophe representing hamzah or ayn.

Examples

010. Source of the derived spelling

Derive the spelling of an Arabic term from its vocalised name according to this standard.

Examples

011. Vocalising the Arabic name

Use vocalised Arabic when deriving a spelling. Write hamzat al-wasl as an alif carrying its vowel, and do not assume an unrecorded vowel.

Examples

Unvocalised «استعاذة» is insufficient to determine the spelling. Write اِ rather than ٱ.

012. Reconstructing the Arabic name

Do not rely on the code name to reconstruct the original Arabic letters.

Examples

Store the original Arabic separately; s alone does not identify which of the two letters occurred in the name.

013. Consonant correspondences

Transliterate consonants using the correspondences in the example.

Examples

014. Short vowels

Represent short vowels as a for fathah, i for kasrah and u for dammah.

Examples

015. Forms of long alif

Treat alif maqsura, dagger alif and maddah as long alif.

Examples

016. Diphthongs

Write waw with sukun following a fathah as aw, and yaa with sukun following a fathah as ay.

Examples

The mawdi example demonstrates only the transliteration of «مَوْضِع»; it does not choose the concept’s final name. When the word means a general location, the general-word table records place, following rule 003.

017. Doubled consonants

Double the consonant carrying a shaddah. The nisbah ending is covered in rule 022.

Examples

018. Tanwin and case endings

Keep only the short vowel of tanwin, and drop the grammatical case vowel at the end of a word.

Examples

Spelling: ta marbutah

019. Ta marbutah outside idafah

Write ta marbutah as h at the end of a name or before an adjective when the word is not the first member of an idafah construction.

Examples

A following word alone does not turn ta marbutah into t: «الصغرى» is an adjective, so write qalqalah_sughra, not qalqalat_sughra.

020. Ta marbutah in idafah

Write ta marbutah as t when its word is the first member of an idafah construction, a noun construction expressing a relationship such as possession.

Examples

Ta marbutah is pronounced as a taa in idafah, so write hamzat_al_wasl, not hamzah_al_wasl.

Spelling: long vowels and letter names

021. Long vowels

Write long vowels with a single Latin letter: a, i or u. Letter names have canonical spellings in rule 023.

Examples

Do not double letters to represent vowel length: write tajwid and nuzul, not tajweed and nuzool. Other forms may be used for display or search, as explained in rule 024.

022. The nisbah ending

Write the doubled yaa of a final nisbah ending, an Arabic adjective ending indicating affiliation, as a single i.

Examples

This applies specifically to the final nisbah yaa: write makki, not makkiyy or makkee. The doubled kaf remains kk under rule 017.

023. Letter-name spellings

Use the spellings recorded in the letter-name table, whether the letter name occurs alone or in a compound.

Examples

Letter names are exceptions to shortened long vowels in rule 021: write noon and meem, not nun and mim. The exception applies to the letter name even within a compound; it does not extend to terms such as tajwid.

Two letter names may share a spelling: taa for taa and emphatic taa, and haa for haa and the pharyngeal haa. These are written names, not unique letter identifiers. When distinguishing them, retain the Arabic letter or its codepoint alongside the name; do not infer the letter from taa or haa alone. This does not permit two concepts to share one dictionary identifier.

024. Common spelling and the derived form

When a common spelling differs from the derived form, use the common spelling for display and search, while keeping the derived form as the code name.

Examples

In the dictionary, code holds the derived form tajwid, display holds Tajweed, and alternative_spellings records tajweed for search. This keeps code spelling predictable while accommodating common usage.

Spelling: hamzah, ayn and exceptions

025. Hamzah and ayn

Omit letters or special marks representing hamzah and ayn, retaining their vowels within a word.

Examples

Omit the mark representing the consonant, not its vowel: write qiraah, not qira'ah, and retain the fathah in muallim. When precise scholarly transliteration is needed, store it in names.transliteration for display or scholarly content without changing the code name.

026. Final hamzah and ayn after a consonant with sukun

Repeat the preceding vowel when a word ends in hamzah or ayn preceded by a consonant with sukun.

Examples

Repeating the vowel avoids shortening the ending to forms such as rub and jam, which are English words with other meanings. If hamzah or ayn follows a long vowel, add nothing: write رُكُوع → ruku and مَمْنُوع → mamnu, because the spelling already ends in a vowel.

027. Established-spelling exceptions

When a term has a documented exception in the established-spellings table, use that recorded spelling instead of the derived result. Add a usage-based exception only through an explicit review decision supported by documented measurements showing the derived result is rare within a defined source set, following the usage-evidence policy. No automatic percentage grants an exception; the decision must explain why the derived form is unsuitable for this term.

Examples

A spelling being more common is not sufficient for an exception; otherwise tajweed would replace tajwid. The exception needs a term-specific justification within the declared measurement scope. Exceptions and measurements are recorded in the established-spellings table.

028. The name of surah Aal Imran

Write the surah name Aal Imran as aal_imran to distinguish «آل» from the definite article al.

Examples

029. Surahs named after their opening letters

Use the recorded names for the surahs Taha, Yasin, Saad and Qaaf, which are named after their opening letters.

Examples

Spelling: articles and connecting words

030. The definite article and sun letters

When the definite article remains inside a compound, write it consistently as al; do not change it before sun letters, the consonants that assimilate its pronunciation.

Examples

031. The definite article at the beginning

Omit the definite article at the beginning of a code name.

Examples

032. The definite article on an adjective

Omit the definite article from an adjective following a definite noun.

Examples

033. The definite article in idafah

Retain al on the second member of an idafah construction, determining the idafah or adjective relationship between each adjacent pair of words.

Examples

034. The definite article after translating a head noun

Exclude a translated head noun when deciding whether to retain the definite article in the rest of the name.

Examples

035. Attached prepositions

When بِ or لِ is attached to a word inside a term, represent the preposition as a separate part of the code name and retain the definite article on the noun following it.

Examples

036. Connecting words

Omit مَعَ, كَوْن, بِحَيْثُ and جَوَازًا from the code name when they only connect its parts, while keeping the Arabic name complete.

Examples

Forms of a name

One concept may have different name forms because each serves a different use: a stable code name, a user-facing name, vocalised Arabic, and names preserved from sources. Different forms do not imply different concepts.

The dictionary reader guide explains naming fields and entry structure. The dictionary contribution section explains how to propose a term or change its definition.

037. Code-name stability

Use the canonical code name unchanged; do not change it merely because a more common spelling appears.

Examples

tajwid remains the code name even when Tajweed is common in display.

038. Choosing the display name

Choose the most common English spelling for display and document the evidence in names.display_evidence before marking the entry adopted. A draft may have a display name before its evidence is complete. The display name is what readers see in interfaces and documentation, and it may differ from the code name.

Examples

Document sources, comparison method and results under the usage-evidence policy. “Most common” means most common within the declared relevant sources, not proven dominance across every possible use.

039. The vocalised Arabic name

Retain the vocalised Arabic name of a Quranic or scholarly Arabic term for derivation and Arabic display.

Examples

040. Source names and the standard's name

Distinguish the standard's name from a source's name or shape description. Preserve the source's wording and attribute it. This applies when a mark's name or classification differs between the standard and the science of mushaf marks, a mushaf introduction or another source.

Examples

041. Changing the Arabic name

Change the vocalised Arabic name only for a linguistic reason that clarifies the concept, never to obtain a preferred code name.

Examples

Do not shorten a waqf value's Arabic name merely to shorten its code name. In this example, the shortened name omits that continuing is preferable.

The shortened form is an illustrative counter-example showing the lost meaning, not a name attributed to a source.

042. Definite articles in Arabic names

Write singular Arabic nouns with the definite article, and classification values expressed as adjectives without it.

Examples

043. Unicode character names

Preserve the official Unicode character name as given; do not use it as the code name of the concept the character represents.

Examples

044. Alternative spellings

Distinguish alternative spellings from lookup forms differing only in case or separators. Both may be recorded in alternative_spellings so that references resolve, but a separator change does not create a distinct linguistic spelling or a new canonical name.

Examples

Relationships between names

045. Relationships between names

Distinguish a canonical name, alternative spelling, English equivalent and deprecated name; these are different relationships between names.

Examples

Deprecated names

046. Deprecated names

Distinguish a valid name no longer recommended for new projects from an alternative spelling, and identify it as a deprecated name referring to the same concept.

Examples

047. References from former names

When a concept is renamed or names for the same concept are merged, preserve the old names and their references to the surviving name, with the date and reason. This also applies when a name is withdrawn from the standard.

Examples

Record the reason for the merge alongside the reference.

Singular and plural

048. Singular and plural

Use the singular for one item and the plural for a collection.

Examples

049. Forming the code plural

Form the code plural by adding s to the complete code name, including compound names.

Examples

ayahs
juzs
hizbs
mushafs

Do not use Arabic plurals such as ayat and suwar as code collection names; write ayahs and surahs. Preserve the Arabic plural as linguistic information in the dictionary.

Classification and value names

050. Classification names and the _type suffix

Name a classification after what it classifies, and reserve the _type suffix for classifications of mark types.

Examples

051. The mark, its indication and the waqf ruling

Use waqf_mark for the drawn mark, waqf_mark_type to classify what the marks indicate, and waqf_ruling to classify the ruling on stopping at a location.

Examples

052. Naming and defining classification values

Give each meaningful type or classification value its own code name and definition; defining only the overall classification is insufficient.

Examples

053. Distinguishing classification-value names

Add the distinguishing concept name to a classification value's name when needed, retaining the words that distinguish it from other values.

Examples

waqf_lazim
waqf_jaiz_wasl_awla

054. Uniqueness within a classification

A value name may occur in two different classifications when its classification is known. It must be unique within its own classification.

Examples

055. Ayah numbering system names

Use the school's name as the code value for an ayah numbering system, rather than deriving the full Arabic name.

Examples

kufi
basri
dimashqi
makki
madani_first
madani_last

Surah and personal names

056. Personal names

Write the names of qiraah transmitters, rawis and other people associated with Quranic terminology using the scholarly English form with transliteration marks removed, supported by evidence for that form. If it conflicts with an explicit rule of the standard, the rule takes precedence: write shubah, not shuba, following the ta marbutah rule.

Examples

hafs
warsh
qalun
ibn_dhakwan

057. Deriving surah names

Derive surah names from their Arabic names using the general spelling rules.

Examples

fatihah
baqarah
nisa

058. A concept and an individual sharing a name

A concept and an individual may share a name when the individual's kind is known and no confusion arises; the bare name refers to the concept. This applies when a reciter or surah shares a name with a Quranic concept.

Examples

Distinguishing concepts

059. Distinguishing neighbouring concepts

Similar names or translations are not a reason to merge different concepts, and one concept's name must not be assigned to another.

Examples

They may coincide in an example, but that does not make the names synonyms.

060. A mark and what it signifies

Give a drawn mushaf mark a name that distinguishes it from the concept it signifies.

Examples

061. Sajdah and its mark

Use sajdah for a location of recitation prostration and the prostration there, and sajdah_mark for the drawn mark.

Examples

062. Naming a mark in context

Identify a Quranic mark by its meaning at its location; its codepoint alone does not determine its name.

Examples

063. Words and their analysis units

Use word for a word in the text, token for a unit produced by segmentation, and morphological-analysis names for what is derived from the word. Do not use these names interchangeably.

Examples

064. Text units and their representation

Choose a text-unit name according to what is meant: a linguistic letter, character, codepoint, grapheme or drawn glyph.

Examples

065. The Quran and the mushaf

Use quran for the Quran and mushaf for the book in which it is written; do not substitute one name for the other.

Examples

066. Content and presentation

Use content-unit names for what the text contains, and presentation names for how it appears on the page.

Examples

Numbers, references and timing

067. Internal identifiers

Use id for an internal identifier linking records; do not show it to readers or build external references on it. Use number for the number readers recognise and cite.

Examples

068. Reference numbers

Use number for an item's recognised number within its domain, displayed to readers and used in citations.

Examples

surah_number
ayah_number
page_number

069. Position in a sequence

Use position for an item's location within a parent or sequence; it is not a stable reference if the sequence changes.

Examples

word_position
token_position
line_position

070. Semantic order

Use order for an intended semantic ordering when it differs from position in the sequence.

Examples

revelation_order
display_order

071. Composite references

Use key for a readable composite reference: ayah_key combines surah and ayah numbers, and word_key combines the ayah key and word position.

Examples

ayah_key = surah_number:ayah_number
2:255

word_key = ayah_key:word_position
2:255:3

072. The numbering system of a reference

The meaning of ayah_key and word_key depends on the ayah numbering system. This standard uses kufi as the default when none is stated.

Examples

ayah_key: 2:255

Interpret references within the declared numbering system, defaulting to kufi. The sequential index of ayahs across the whole mushaf is a position and also depends on the numbering system. The numbering system alone does not make word_key stable when the text or segmentation differs; identify the text and segmentation method when exchanging word references.

073. Naming audio timings

Within a particular recitation recording, name an audio span after the text unit it corresponds to: ayah_timing for an ayah and word_timing for a word, without including the reciter, riwayah or style in the name.

Examples

Using names in software

These guidelines supplement the terminology rules when using names in a model, database or API.

Clear names

Use a complete, familiar name such as surah, ayah or word, avoiding abbreviations such as srh, ay and wrd. Choose a name that identifies the data rather than data or item when its kind is known.

Relationship names

Name a relationship after the linked concept, using singular for a to-one relationship and plural for a to-many relationship: ayah.surah, surah.ayahs and ayah.words. For a data relationship, ayahs is sufficient; getAyahList() describes an operation that retrieves it.

Operation names

Use the same verb for the same operation: normalize, parse, tokenize, segment, transliterate, annotate, render, validate, compare and convert. tokenizeText() explains the work more clearly than processText(), and renderAyah() is more precise than handleAyah() when the operation displays an ayah. These are operation names and do not need separate dictionary entries.

Boolean names

Make a boolean field's name a yes/no question, such as has_sajdah or is_active. When choosing a value from a classification with several values, use that classification field rather than multiple booleans whose values could conflict.

The same vocabulary across system layers

Keep canonical vocabulary in models, databases and APIs, adapting letter case to the layer. For example, the Surah model corresponds to the surahs table and surah_id linking field; it does not become chapter in another layer. The interface may display an appropriate translation for the reader.

Changing case or separators does not create an independent linguistic spelling; the form may be recorded for lookup under rule 044.

Names owned by an external source

Preserve external package, file and column names exactly as their owner writes them, because changing them breaks the reference. For example, retain row["aya_text_emlaey"] when reading a publisher's file. Fields created inside your project after reading it follow the standard. Declare these external names to the auditor through external_names in .terminology.json.

Link timings to their recording

ayah_timing carries recitation_id, ayah_key, start_ms and end_ms; word_timing uses word_key instead of the ayah key. recitation_id identifies the recording the times belong to. Store the reciter, riwayah and style on the recitation, without adding them to the audio-span name.