{
  "openapi": "3.1.0",
  "info": {
    "title": "DiArMaqAr API",
    "version": "1.0.0",
    "description": "Digital Arabic Maqām Archive (DiArMaqAr) — programmatic access to Arabic maqāmāt, ajnās, and tuning systems data\n\nKey features:\n- Maqāmāt and ajnās database with bibliographic source attribution\n- Historical tuning systems with multiple starting note contexts\n- Multiple pitch class data formats (fractions, ratios, decimal ratio, string length, fret divisions, frequency, cents, MIDI notes, and more)\n- Tuning system sensitive transpositions\n- Modulations via al-Shawwā's 1946 modulation guidelines\n- Interactive API documentation with live endpoint testing capabilities \n",
    "contact": {
      "name": "Khyam Allami",
      "email": "ka109@aub.edu.lb",
      "url": "https://musicintelligencelab.com"
    },
    "license": {
      "name": "CC-BY-NC-SA 4.0",
      "url": "https://creativecommons.org/licenses/by-nc-sa/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://diarmaqar.netlify.app/api",
      "description": "Production server"
    },
    {
      "url": "http://localhost:3000/api",
      "description": "Development server"
    }
  ],
  "paths": {
    "/maqamat": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "List all maqāmāt",
        "description": "Retrieve all available maqāmāt with optional filtering and sorting.\n\n**Returns:** All maqāmāt with their tuning system availability information. This endpoint does **not** include note names or pitch class data—only metadata about which tuning systems can realize each maqām.\n\nReturns concise metadata including:\n- URL-safe identifiers and display names for each maqām\n- Maqām family and maqām tonic identifiers (both URL-safe and display formats)\n- Availability counts across tuning systems with their valid starting note names (e.g., \"ʿushayrān\", \"yegāh\" etc...)\n- Optional bibliographic source references (sourceId and page) when `includeSources=true`\n- Filter values must be URL-safe; see parameter enums for complete list of valid options\n\n**Note:** For detailed pitch class data, note names, and ajnās information, use the `/maqamat/{idName}` endpoint.\n",
        "operationId": "listMaqamat",
        "parameters": [
          {
            "name": "filterByFamily",
            "in": "query",
            "description": "Filter by maqām family name (URL-safe, case-insensitive, diacritics-insensitive).\nUse GET /maqamat/families to retrieve valid family values.\n",
            "schema": {
              "type": "string",
              "enum": [
                "ajam",
                "athar_kurd",
                "awj_ara",
                "bayyat",
                "buselik",
                "chahargah",
                "hijaz",
                "iraq",
                "kurd",
                "nahawand",
                "nikriz",
                "no_jins",
                "rast",
                "saba",
                "saba_zamzam",
                "segah"
              ]
            },
            "example": "rast"
          },
          {
            "name": "filterByTonic",
            "in": "query",
            "description": "Filter by maqām tonic/first note (URL-safe, case-insensitive, diacritics-insensitive)",
            "schema": {
              "type": "string",
              "enum": [
                "ajam_ushayran",
                "chahargah",
                "dugah",
                "iraq",
                "nawa",
                "rast",
                "segah",
                "ushayran",
                "yegah"
              ],
              "example": "rast"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": [
                "tonic",
                "alphabetical"
              ],
              "default": "alphabetical"
            },
            "examples": {
              "tonic": {
                "value": "tonic",
                "summary": "Sort by tonic note priority (NoteName.ts order)"
              },
              "alphabetical": {
                "value": "alphabetical",
                "summary": "Sort alphabetically by display name"
              }
            }
          },
          {
            "name": "includeSources",
            "in": "query",
            "required": false,
            "description": "Include bibliographic source references (sourceId and page) for each maqām",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "List of maqāmāt retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MaqamatListResponse"
                },
                "examples": {
                  "default": {
                    "summary": "Default response (includeArabic=false)",
                    "value": {
                      "count": 60,
                      "data": [
                        {
                          "id": "29",
                          "idName": "maqam_yegah",
                          "displayName": "maqām yegāh",
                          "version": "2025-10-18T19:41:17.132Z",
                          "familyId": "no_jins",
                          "familyDisplay": "no jins",
                          "tonicId": "yegah",
                          "tonicDisplay": "yegāh",
                          "numberOfPitchClasses": 7,
                          "isOctaveRepeating": true,
                          "hasAsymmetricDescending": true,
                          "hasSuyur": true,
                          "availableInTuningSystems": 4,
                          "tuningSystemsAvailability": [
                            {
                              "tuningSystemId": "alfarabi_950g",
                              "tuningSystemStartingNoteNames": [
                                "ʿushayrān"
                              ]
                            },
                            {
                              "tuningSystemId": "cairocongresstuningcommittee_1929",
                              "tuningSystemStartingNoteNames": [
                                "yegāh"
                              ]
                            },
                            {
                              "tuningSystemId": "alsabbagh_1954",
                              "tuningSystemStartingNoteNames": [
                                "rāst"
                              ]
                            },
                            {
                              "tuningSystemId": "allami_2025",
                              "tuningSystemStartingNoteNames": [
                                "rāst"
                              ]
                            }
                          ],
                          "maqamDetailsUrl": "/api/maqamat/maqam_yegah",
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "49"
                            }
                          ]
                        },
                        {
                          "id": "30",
                          "idName": "maqam_farahfazza",
                          "displayName": "maqām faraḥfazzā",
                          "version": "2025-10-18T19:41:17.132Z",
                          "familyId": "no_jins",
                          "familyDisplay": "no jins",
                          "tonicId": "yegah",
                          "tonicDisplay": "yegāh",
                          "numberOfPitchClasses": 7,
                          "isOctaveRepeating": true,
                          "hasAsymmetricDescending": true,
                          "hasSuyur": true,
                          "availableInTuningSystems": 35,
                          "tuningSystemsAvailability": [
                            {
                              "tuningSystemId": "ronzevalle_1904",
                              "tuningSystemStartingNoteNames": [
                                "ʿushayrān",
                                "yegāh"
                              ]
                            },
                            {
                              "tuningSystemId": "alfarabi_950g",
                              "tuningSystemStartingNoteNames": [
                                "ʿushayrān"
                              ]
                            }
                          ],
                          "maqamDetailsUrl": "/api/maqamat/maqam_farahfazza",
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "50"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "bilingual": {
                    "summary": "Bilingual response (includeArabic=true)",
                    "value": {
                      "count": 60,
                      "data": [
                        {
                          "id": "29",
                          "idName": "maqam_yegah",
                          "displayName": "maqām yegāh",
                          "displayNameAr": "مقام يگاه",
                          "version": "2025-10-18T19:41:17.132Z",
                          "familyId": "no_jins",
                          "familyDisplay": "no jins",
                          "familyDisplayAr": "لا جنس",
                          "tonicId": "yegah",
                          "tonicDisplay": "yegāh",
                          "tonicDisplayAr": "يگاه",
                          "numberOfPitchClasses": 7,
                          "isOctaveRepeating": true,
                          "hasAsymmetricDescending": true,
                          "hasSuyur": true,
                          "availableInTuningSystems": 4,
                          "tuningSystemsAvailability": [
                            {
                              "tuningSystemId": "alfarabi_950g",
                              "tuningSystemStartingNoteNames": [
                                "ʿushayrān"
                              ],
                              "tuningSystemStartingNoteNamesAr": [
                                "عشيران"
                              ]
                            },
                            {
                              "tuningSystemId": "cairocongresstuningcommittee_1929",
                              "tuningSystemStartingNoteNames": [
                                "yegāh"
                              ],
                              "tuningSystemStartingNoteNamesAr": [
                                "يگاه"
                              ]
                            }
                          ],
                          "maqamDetailsUrl": "/api/maqamat/maqam_yegah",
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "49"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "emptyFamily": {
                    "summary": "Empty filterByFamily parameter",
                    "value": {
                      "error": "Invalid parameter: filterByFamily",
                      "message": "The 'filterByFamily' parameter cannot be empty. Either omit it or provide a valid maqām family name.",
                      "hint": "Remove '?filterByFamily=' from your URL, specify a family like '?filterByFamily=rast', or use GET /maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah for valid values"
                    }
                  },
                  "emptyTonic": {
                    "summary": "Empty filterByTonic parameter",
                    "value": {
                      "error": "Invalid parameter: filterByTonic",
                      "message": "The 'filterByTonic' parameter cannot be empty. Either omit it or provide a valid tonic note name.",
                      "hint": "Remove '?filterByTonic=' from your URL or specify a tonic like '?filterByTonic=rast'"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/families": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "List maqām families",
        "description": "Retrieve maqām families for maqāmāt available in the specified tuning system.\nFamilies are classified by the first jins at scale degree 1. Use the `maqamat`\nlink to filter maqāmāt by family via GET /maqamat?filterByFamily={idName}.\n",
        "operationId": "listMaqamFamilies",
        "parameters": [
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system identifier (e.g., ibnsina_1037, alsabbagh_1954)",
            "schema": {
              "type": "string"
            },
            "example": "ibnsina_1037"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Starting note name (URL-safe, diacritics-insensitive)",
            "schema": {
              "type": "string"
            },
            "example": "yegah"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Include Arabic display names in family objects",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Maqām families retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "data"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Number of families"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "family",
                          "links"
                        ],
                        "properties": {
                          "family": {
                            "$ref": "#/components/schemas/IdentifierRef"
                          },
                          "links": {
                            "type": "object",
                            "properties": {
                              "maqamat": {
                                "type": "string",
                                "description": "URL to filter maqāmāt by this family",
                                "example": "/api/maqamat?filterByFamily=rast"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "count": 16,
                  "data": [
                    {
                      "family": {
                        "idName": "rast",
                        "displayName": "rāst"
                      }
                    },
                    {
                      "family": {
                        "idName": "bayyat",
                        "displayName": "bayyāt"
                      }
                    },
                    {
                      "family": {
                        "idName": "hijaz",
                        "displayName": "ḥijāz"
                      }
                    },
                    {
                      "family": {
                        "idName": "ajam",
                        "displayName": "ʿajam"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Tuning system or starting note not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/{idName}": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "Get detailed maqām data",
        "description": "Retrieve comprehensive data for a specific maqām on its conventional or a transposed tonic, in a specific tuning system on a specific starting note name.\n\n**Special Path Parameter Value:**\n- The `{idName}` path parameter accepts the special value `\"all\"` to retrieve data for all maqāmāt in a specific tuning system and starting note\n- When using `\"all\"`, both `tuningSystem` and `startingNote` query parameters are required\n\nReturns:\n- Comprehensive pitch class data in the requested tuning system and starting note name\n- All ajnās present at each maqām degree in the ascending and descending maqām structure, organized by their maqām degree note names\n- Optional includeIntervals data, transposition to different tonics, tuning-system-specific modulations (including lower octave), and suyūr\n\nParameter Discovery:\n- Use options=true to discover valid values for all parameters including dynamically calculated transposition options\n- Especially useful for finding valid tuning system starting notes and transposition tonics for a specific maqām\n\nImportant:\n- When options=true, the endpoint returns parameter discovery metadata instead of maqām data\n- This mode is mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, include suyūr, pitch class data type, includeIntervals)\n- If data-returning parameters are provided with options=true, the API returns a 400 Bad Request error with details about conflicting parameters\n\nRequirements:\n- Tuning system and starting note are required for all requests (both data retrieval and discovery mode)\n- These are fundamental to all pitch class calculations\n",
        "operationId": "getMaqam",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe maqām identifier.\n\n**Special value**: Use `\"all\"` to retrieve data for all maqāmāt in a specific tuning system and starting note. When using `\"all\"`, both `tuningSystem` and `startingNote` query parameters are required.\n",
            "schema": {
              "type": "string"
            },
            "examples": {
              "rast": {
                "value": "maqam_rast",
                "summary": "Maqām Rāst (representative example)"
              },
              "bayyat": {
                "value": "maqam_bayyat",
                "summary": "Maqām Bayyāt (representative example)"
              },
              "hijaz": {
                "value": "maqam_hijaz",
                "summary": "Maqām Ḥijāz (representative example)"
              },
              "all": {
                "value": "all",
                "summary": "All maqāmāt (requires tuningSystem and startingNote query parameters)"
              }
            }
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899')",
            "schema": {
              "type": "string"
            },
            "examples": {
              "ibnsina": {
                "value": "ibnsina_1037",
                "summary": "Ibn Sīnā (1037) - 7-Fret Oud 17-Tone (representative example)"
              },
              "farabi": {
                "value": "alfarabi_950g",
                "summary": "al-Fārābī (950g) - First Oud Tuning 27-Tone (representative example)"
              },
              "meshshaqa": {
                "value": "meshshaqa_1899",
                "summary": "Meshshāqa (1899) - Arabic Octave According to the Modernists (representative example)"
              }
            }
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive).\n\n- Mandatory for all pitch class calculations\n- Different starting notes represent different theoretical frameworks within the same tuning system\n- Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string"
            },
            "examples": {
              "yegah": {
                "value": "yegah",
                "summary": "yegāh (for IbnSina, Meshshaqa)"
              },
              "ushayran": {
                "value": "ushayran",
                "summary": "ʿushayrān (for al-Farabi, al-Kindi)"
              },
              "rast": {
                "value": "rast",
                "summary": "rāst (for CairoCongress, al-Sabbagh)"
              }
            }
          },
          {
            "name": "options",
            "in": "query",
            "description": "When true, returns available parameter options instead of maqām data.\n\n- Useful for discovering valid values for tuning systems, starting notes, and other parameters\n- Tuning system and starting note are required for all requests (both data retrieval and discovery mode)\n- These are fundamental to all pitch class calculations and calculate valid starting note options and transposition tonics\n- Mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, include suyūr, pitch class data type, includeIntervals)\n- Transposition options are dynamically calculated based on the specific maqām, tuning system, and starting note combination\n- Only tonics where the maqām can be validly transposed (preserving interval pattern) are included, not all possible pitch classes\n- If data-returning parameters are provided, returns 400 Bad Request error with details about conflicting parameters\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": false,
            "description": "Specifies which pitch class data type to return for each pitch class.\n\n- Optional parameter. When omitted, returns only minimal pitch class fields: `pitchClassIndex`, `octave`, `scaleDegree`, `noteName`, `noteNameDisplay`, and `noteNameDisplayAr` (if includeArabic is enabled)\n- When provided, returns the specified data type for all pitch classes in the maqām\n- In discovery mode (when options=true), this parameter is optional since the response returns parameter metadata instead of formatted data\n- Use 'all' for complete pitch class data across all available formats\n",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "abjadName",
                "englishName",
                "solfege",
                "fraction",
                "cents",
                "centsDeviation",
                "decimalRatio",
                "stringLength",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "frequency",
                "referenceNoteName"
              ]
            },
            "example": "cents"
          },
          {
            "name": "transposeTo",
            "in": "query",
            "description": "Transpose the maqām to a new tonic by preserving the interval patterns (URL-safe, diacritics-insensitive).\n\n- Only tonics where the maqām can be validly transposed in the specified tuning system and starting note are valid\n- To see all valid transposition options, request available parameter options instead of maqām data\n",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "includeIntervals",
            "in": "query",
            "description": "Include interval data between maqām degrees",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeModulations",
            "in": "query",
            "description": "Include modulation possibilities to other maqāmāt and ajnās",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeModulations8vb",
            "in": "query",
            "description": "Include available modulations an octave below",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeSuyur",
            "in": "query",
            "description": "Include suyūr (melodic paths) data",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Maqām data retrieved successfully.\n\n- When options is true, the response structure differs and returns available parameter options instead of maqām data\n- In that case, transposition options contain only valid transposition tonics for this specific maqām, tuning system, and starting note combination\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MaqamDetailResponse"
                },
                "examples": {
                  "basic": {
                    "summary": "Basic maqām data with ajnās (default)",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "maqām rāst",
                        "version": "2025-10-18T19:41:17.132Z",
                        "tonicId": "rast",
                        "tonicDisplay": "rāst",
                        "transposition": false,
                        "familyId": "rast",
                        "familyDisplay": "rāst",
                        "numberOfTranspositions": 3,
                        "numberOfMaqamModulations": 28,
                        "numberOfAjnasModulations": 29,
                        "commentsEnglish": null,
                        "commentsArabic": null,
                        "sources": [],
                        "pitchClassDataType": "cents",
                        "includeIntervals": false
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
                          "version": "2025-10-18T19:42:23.643Z",
                          "originalValueType": "fraction",
                          "numberOfPitchClassesSingleOctave": 17,
                          "numberOfPitchClassesAllOctaves": 68,
                          "tuningSystemStartingNoteNames": [
                            "ʿushayrān",
                            "yegāh"
                          ],
                          "tuningSystemStartingNoteNamesIds": [
                            "ushayran",
                            "yegah"
                          ],
                          "startingNoteName": "yegah",
                          "referenceFrequency": 97.999
                        },
                        "pitchClassDataType": "cents",
                        "includeIntervals": false
                      }
                    }
                  },
                  "minimal": {
                    "summary": "Minimal fields (pitchClassDataType omitted)",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "maqām rāst",
                        "version": "2025-10-18T19:41:17.132Z",
                        "tonicId": "rast",
                        "tonicDisplay": "rāst",
                        "transposition": false,
                        "familyId": "rast",
                        "familyDisplay": "rāst",
                        "numberOfTranspositions": 3,
                        "numberOfMaqamModulations": 28,
                        "numberOfAjnasModulations": 29,
                        "commentsEnglish": null,
                        "commentsArabic": null,
                        "sources": []
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
                          "version": "2025-10-18T19:42:23.643Z",
                          "originalValueType": "fraction",
                          "numberOfPitchClassesSingleOctave": 17,
                          "numberOfPitchClassesAllOctaves": 68,
                          "tuningSystemStartingNoteNames": [
                            "ʿushayrān",
                            "yegāh"
                          ],
                          "tuningSystemStartingNoteNamesIds": [
                            "ushayran",
                            "yegah"
                          ],
                          "startingNoteName": "yegah",
                          "referenceFrequency": 97.999
                        }
                      },
                      "pitchData": {
                        "ascending": [
                          {
                            "pitchClassIndex": 4,
                            "octave": 1,
                            "scaleDegree": "I",
                            "noteName": "rast",
                            "noteNameDisplay": "rāst"
                          },
                          {
                            "pitchClassIndex": 7,
                            "octave": 1,
                            "scaleDegree": "II",
                            "noteName": "dugah",
                            "noteNameDisplay": "dūgāh"
                          }
                        ],
                        "descending": [
                          {
                            "pitchClassIndex": 16,
                            "octave": 2,
                            "scaleDegree": "VII",
                            "noteName": "ajam",
                            "noteNameDisplay": "ʿajam"
                          }
                        ]
                      },
                      "ajnas": {
                        "ascending": {
                          "rast": {
                            "id": "3",
                            "idName": "jins_rast",
                            "displayName": "jins rāst"
                          },
                          "dugah": null
                        },
                        "descending": {
                          "ajam": {
                            "id": "7",
                            "idName": "jins_ajam",
                            "displayName": "jins ʿajam"
                          }
                        }
                      }
                    }
                  },
                  "transposed": {
                    "summary": "Transposed maqām (taṣwīr)",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "maqām rāst",
                        "version": "2025-10-18T19:41:17.132Z",
                        "tonicId": "nawa",
                        "tonicDisplay": "nawā",
                        "transposition": true,
                        "originalTonicId": "rast",
                        "originalTonicDisplay": "rāst",
                        "transposedTonicId": "nawa",
                        "transposedTonicDisplay": "nawā",
                        "familyId": "rast",
                        "familyDisplay": "rāst",
                        "numberOfTranspositions": 3,
                        "numberOfMaqamModulations": 28,
                        "numberOfAjnasModulations": 29,
                        "commentsEnglish": null,
                        "commentsArabic": null,
                        "sources": [],
                        "pitchClassDataType": "all",
                        "includeIntervals": false
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā  (1037) 7-Fret Oud 17-Tone",
                          "version": "2025-10-18T19:42:23.643Z",
                          "originalValueType": "fraction",
                          "numberOfPitchClassesSingleOctave": 17,
                          "numberOfPitchClassesAllOctaves": 68,
                          "tuningSystemStartingNoteNames": [
                            "ʿushayrān",
                            "yegāh"
                          ],
                          "tuningSystemStartingNoteNamesIds": [
                            "ushayran",
                            "yegah"
                          ],
                          "startingNoteName": "yegah",
                          "referenceFrequency": 97.999
                        },
                        "pitchClassDataType": "all",
                        "includeIntervals": false
                      },
                      "pitchData": {
                        "ascending": [
                          {
                            "pitchClassIndex": 4,
                            "octave": 1,
                            "scaleDegree": "I",
                            "noteName": "rast",
                            "noteNameDisplay": "rāst",
                            "englishName": "C3",
                            "solfege": "Do3",
                            "fraction": "32/27",
                            "cents": 294.135,
                            "decimalRatio": 1.185,
                            "stringLength": 843.75,
                            "frequency": 130.37,
                            "fretDivision": "156.250",
                            "midiNoteDecimal": 47.941,
                            "midiNotePlusCentsDeviation": "48 -5.9",
                            "centsDeviation": -5.865,
                            "ipnReferenceNoteName": "C"
                          },
                          {
                            "pitchClassIndex": 7,
                            "octave": 1,
                            "scaleDegree": "II",
                            "noteName": "dugah",
                            "noteNameDisplay": "dūgāh",
                            "englishName": "D3",
                            "solfege": "Re3",
                            "fraction": "4/3",
                            "cents": 498.045,
                            "decimalRatio": 1.333,
                            "frequency": 146.667
                          }
                        ],
                        "descending": [
                          {
                            "pitchClassIndex": 16,
                            "octave": 2,
                            "scaleDegree": "VII",
                            "noteName": "ajam",
                            "noteNameDisplay": "ʿajam",
                            "frequency": 195.998
                          }
                        ]
                      },
                      "ajnas": {
                        "ascending": {
                          "rast": {
                            "id": "3",
                            "idName": "jins_rast",
                            "displayName": "jins rāst"
                          },
                          "dugah": null
                        },
                        "descending": {
                          "ajam": {
                            "id": "7",
                            "idName": "jins_ajam",
                            "displayName": "jins ʿajam"
                          }
                        }
                      }
                    }
                  },
                  "withModulations": {
                    "summary": "With modulation networks (reorganized structure)",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "maqām rāst",
                        "tonicName": "rast",
                        "tonicDisplayName": "rāst",
                        "transposition": false,
                        "pitchClassDataType": "cents",
                        "includeIntervals": false
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                          "startingNoteName": "ushayran"
                        }
                      },
                      "pitchData": {
                        "ascending": [],
                        "descending": []
                      },
                      "ajnas": {
                        "ascending": {
                          "rast": {
                            "id": "19",
                            "idName": "jins_rast",
                            "displayName": "jins rāst"
                          },
                          "dugah": {
                            "id": "2",
                            "idName": "jins_bayyat",
                            "displayName": "jins bayyāt"
                          },
                          "segah": {
                            "id": "3",
                            "idName": "jins_segah",
                            "displayName": "jins segāh"
                          }
                        },
                        "descending": {
                          "ajam": null,
                          "husayni": {
                            "id": "7",
                            "idName": "jins_kurd_al-husayni",
                            "displayName": "jins kurd al-ḥusaynī"
                          }
                        }
                      },
                      "modulations": {
                        "maqamat": [
                          {
                            "maqamDegree": "I",
                            "noteNameId": "rast",
                            "noteNameDisplay": "rāst",
                            "pitchClassIndex": 4,
                            "count": 8,
                            "modulations": [
                              {
                                "id": "4",
                                "idName": "maqam_hijaz_kar_kurd",
                                "displayName": "maqām ḥijāz kār kurd"
                              },
                              {
                                "id": "5",
                                "idName": "maqam_nikriz",
                                "displayName": "maqām nikrīz"
                              }
                            ]
                          },
                          {
                            "maqamDegree": "III",
                            "noteNameId": "segah",
                            "noteNameDisplay": "segāh",
                            "pitchClassIndex": 9,
                            "count": 5,
                            "modulations": [
                              {
                                "id": "19",
                                "idName": "maqam_segah",
                                "displayName": "maqām segāh"
                              },
                              {
                                "id": "20",
                                "idName": "maqam_huzam",
                                "displayName": "maqām huzām"
                              }
                            ]
                          },
                          {
                            "maqamDegree": "VI",
                            "noteNameId": "husayni",
                            "noteNameDisplay": "ḥusaynī",
                            "pitchClassIndex": 0,
                            "maqamDegreeDirection": "ascending",
                            "count": 3,
                            "modulations": [
                              {
                                "id": "13",
                                "idName": "maqam_bayyat_shuri_al-husayni",
                                "displayName": "maqām bayyāt shūrī al-ḥusaynī"
                              }
                            ]
                          }
                        ],
                        "ajnas": [
                          {
                            "jinsDegree": "I",
                            "noteNameId": "rast",
                            "noteNameDisplay": "rāst",
                            "pitchClassIndex": 4,
                            "count": 5,
                            "modulations": [
                              {
                                "id": "6",
                                "idName": "jins_nahawand",
                                "displayName": "jins nahāwand"
                              },
                              {
                                "id": "19",
                                "idName": "jins_rast",
                                "displayName": "jins rāst"
                              }
                            ]
                          },
                          {
                            "jinsDegree": "III",
                            "noteNameId": "segah",
                            "noteNameDisplay": "segāh",
                            "pitchClassIndex": 9,
                            "count": 4,
                            "modulations": [
                              {
                                "id": "3",
                                "idName": "jins_segah",
                                "displayName": "jins segāh"
                              }
                            ]
                          }
                        ]
                      }
                    }
                  },
                  "withOptions": {
                    "summary": "Options response (when options=true)",
                    "value": {
                      "maqam": "maqām rāst",
                      "tuningSystem": "ibnsina_1037",
                      "availableParameters": {
                        "tuningSystem": {
                          "required": true,
                          "description": "ID of tuning system (see /availability for options)"
                        },
                        "startingNote": {
                          "options": [
                            "ushayran",
                            "yegah"
                          ],
                          "default": "ushayran",
                          "description": "Theoretical framework for note naming"
                        },
                        "pitchClassDataType": {
                          "options": [
                            "all",
                            "frequency",
                            "cents",
                            "fraction",
                            "decimalRatio",
                            "stringLength",
                            "abjadName",
                            "fretDivision",
                            "midiNoteNumber",
                            "midiNoteDeviation",
                            "centsDeviation",
                            "referenceNoteName",
                            "englishName"
                          ],
                          "default": null,
                          "description": "Output format for pitch data. When omitted, returns only minimal fields (pitchClassIndex, octave, scaleDegree, noteName, noteNameDisplay, noteNameDisplayAr). Use 'all' for complete pitch class information."
                        },
                        "includeIntervals": {
                          "type": "boolean",
                          "default": false,
                          "description": "Include interval data between pitch classes"
                        },
                        "transposeTo": {
                          "options": [
                            "rast",
                            "nawa",
                            "dugah"
                          ],
                          "default": null,
                          "description": "Transpose to specific tonic (taṣwīr) - only valid transpositions shown"
                        },
                        "includeModulations": {
                          "type": "boolean",
                          "default": false,
                          "description": "Include modulation analysis (maqāmāt and ajnās)"
                        },
                        "includeModulations8vb": {
                          "type": "boolean",
                          "default": false,
                          "description": "Include available modulations an octave below"
                        },
                        "includeSuyur": {
                          "type": "boolean",
                          "default": false,
                          "description": "Include documented performance practices (suyūr)"
                        }
                      },
                      "notes": {
                        "ajnasData": "Ajnās (constituent melodic structures) are always included in the response for maqām analysis",
                        "formatOptions": "The 'pitchClassDataType' parameter controls which pitch class properties are returned. When omitted, only minimal fields are returned. Use 'all' for comprehensive data or specific formats like 'cents', 'fraction', etc. for targeted data."
                      },
                      "examples": [
                        "/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&includeIntervals=true",
                        "/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=nawa&includeModulations=true"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "conflictingParametersWithOptions": {
                    "summary": "Conflicting parameters with options=true",
                    "description": "When options=true is used with data-returning parameters, the API returns a 400 Bad Request error",
                    "value": {
                      "error": "Conflicting parameters with options=true",
                      "message": "The following data-returning parameters cannot be used with options=true (parameter discovery mode): includeIntervals",
                      "hint": "Use options=true for parameter discovery. Contextual parameters (tuningSystem, startingNote) are optional but enhance discovery (e.g., show actual transposition options). Remove all data-returning parameters to use discovery mode, or remove options=true to retrieve maqām data.",
                      "conflictingParameters": [
                        "includeIntervals"
                      ],
                      "contextualParametersAllowed": [
                        "tuningSystem",
                        "startingNote"
                      ]
                    }
                  },
                  "missingTuningSystem": {
                    "summary": "Missing required tuningSystem parameter",
                    "value": {
                      "error": "tuningSystem parameter is required",
                      "hint": "Use /api/maqamat/{idName}/availability to see available tuning systems",
                      "availabilityUrl": "/api/maqamat/{idName}/availability"
                    }
                  },
                  "missingStartingNote": {
                    "summary": "Missing required startingNote parameter",
                    "value": {
                      "error": "startingNote parameter is required",
                      "message": "A tuning system starting note must be specified. This is mandatory for all pitch class calculations.",
                      "validOptions": [
                        "ʿushayrān",
                        "yegāh"
                      ],
                      "hint": "Add &startingNote=ʿushayrān to your request"
                    }
                  },
                  "invalidStartingNote": {
                    "summary": "Invalid startingNote value",
                    "value": {
                      "error": "Invalid startingNote 'invalid_note'",
                      "validOptions": [
                        "ʿushayrān",
                        "yegāh"
                      ],
                      "hint": "Valid starting notes for this tuning system: ʿushayrān, yegāh"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Maqām not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Maqām 'maqam_invalid' not found",
                  "hint": "Use /api/maqamat to see all available maqāmāt"
                }
              }
            }
          },
          "422": {
            "description": "Maqām cannot be realized in the specified tuning system",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Maqām 'maqam_bestenegar' cannot be realized in tuning system 'alkindi_874' with starting note 'ushayran'",
                  "hint": "Use /api/maqamat/{idName}/availability to see compatible tuning systems"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/{idName}/availability": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "Check maqām availability across tuning systems",
        "description": "Return tuning-system availability for a maqām.\n\n- Shows which tuning systems on which starting note names can realize the specified maqām\n- If `transpositionNoteName` is provided, filters results to show only tuning systems where the maqām can be transposed to that specific note\n- Validity is computed against each tuning system's note name sets and the maqām's pitch class intervals\n- Tuning system starting note names are returned as both display values (with diacritics) and URL-safe identifiers\n",
        "operationId": "getMaqamAvailability",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe maqām identifier",
            "schema": {
              "type": "string"
            },
            "example": "maqam_bayyat"
          },
          {
            "name": "transpositionNoteName",
            "in": "query",
            "required": false,
            "description": "Filter results to show only tuning systems where the maqām can be transposed to this specific note (URL-safe, diacritics-insensitive)",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Availability information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "maqam",
                    "availability"
                  ],
                  "properties": {
                    "maqam": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Numeric identifier for the maqām"
                        },
                        "idName": {
                          "type": "string",
                          "description": "URL-safe identifier for the maqām (e.g., \"maqam_rast\")"
                        },
                        "displayName": {
                          "type": "string",
                          "description": "Display name with diacritics (e.g., \"Maqam Rāst\")"
                        },
                        "transpositionNoteName": {
                          "type": "string",
                          "description": "The transposition note name filter applied (present only when transpositionNoteName parameter is provided)",
                          "example": "nawa"
                        },
                        "version": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of last modification"
                        }
                      }
                    },
                    "availability": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "description": "Number of tuning systems supporting this maqām (or supporting the specified transposition if transpositionNoteName is provided)"
                        },
                        "tuningSystems": {
                          "type": "array",
                          "description": "Array of tuning systems where this maqām is available (filtered by transposition if transpositionNoteName is provided)",
                          "items": {
                            "$ref": "#/components/schemas/TuningSystemAvailability"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "withoutTransposition": {
                    "summary": "Without transposition filter",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "Maqam Rāst",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "availability": {
                        "count": 29,
                        "tuningSystems": [
                          {
                            "tuningSystemId": "ibnsina_1037",
                            "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran",
                              "yegah"
                            ]
                          },
                          {
                            "tuningSystemId": "alfarabi_950g",
                            "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran",
                              "yegah"
                            ]
                          }
                        ]
                      }
                    }
                  },
                  "withTransposition": {
                    "summary": "With transposition filter (transpositionNoteName=nawa)",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "Maqam Rāst",
                        "transpositionNoteName": "nawa",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "availability": {
                        "count": 15,
                        "tuningSystems": [
                          {
                            "tuningSystemId": "ibnsina_1037",
                            "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran"
                            ]
                          },
                          {
                            "tuningSystemId": "alfarabi_950g",
                            "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran",
                              "yegah"
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "emptyTranspositionNoteName": {
                    "summary": "Empty transpositionNoteName parameter",
                    "value": {
                      "error": "Invalid parameter: transpositionNoteName",
                      "message": "The 'transpositionNoteName' parameter cannot be empty.",
                      "hint": "Provide a valid note name like ?transpositionNoteName=nawa or remove the parameter"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Maqām not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Maqām 'maqam_invalid' not found",
                  "hint": "Use /api/maqamat to see all available maqāmāt"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tuning-systems": {
      "get": {
        "tags": [
          "Tuning Systems"
        ],
        "summary": "List all tuning systems",
        "description": "Retrieve metadata for all available tuning systems.\n\n- Includes identifiers, display names, version information, primary value type, and pitch class counts per octave\n- Responses include available starting note names for each tuning system\n- Different starting notes represent different theoretical frameworks (e.g., ʿushayrān for oud tuning, yegāh for monochord measurements)\n- Optional bibliographic source references (sourceId and page) when `includeSources=true`\n",
        "operationId": "listTuningSystems",
        "parameters": [
          {
            "name": "includeSources",
            "in": "query",
            "required": false,
            "description": "Include bibliographic source references (sourceId and page) for each tuning system",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "List of tuning systems",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "data"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Total number of tuning systems in the dataset"
                    },
                    "data": {
                      "type": "array",
                      "description": "Array of tuning system objects",
                      "items": {
                        "type": "object",
                        "required": [
                          "tuningSystem",
                          "startingNotes",
                          "stats",
                          "sources"
                        ],
                        "properties": {
                          "tuningSystem": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "startingNotes": {
                            "type": "object",
                            "properties": {
                              "idNames": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "displayNames": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          },
                          "stats": {
                            "type": "object",
                            "properties": {
                              "numberOfPitchClassesSingleOctave": {
                                "type": "integer",
                                "description": "Number of pitch classes per octave"
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "description": "Bibliographic source references for this tuning system",
                            "items": {
                              "type": "object",
                              "properties": {
                                "sourceId": {
                                  "type": "string",
                                  "description": "URL-safe source identifier",
                                  "example": "al-Shawwa-(1946)"
                                },
                                "page": {
                                  "type": "string",
                                  "description": "Page number or range where the tuning system is documented",
                                  "example": "49"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "english": {
                    "summary": "English display names (default, includeArabic=false)",
                    "value": {
                      "count": 35,
                      "data": [
                        {
                          "tuningSystem": {
                            "id": "ibnsina_1037",
                            "idName": "ibnsina_1037",
                            "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                            "version": "2025-10-18T19:42:23.643Z",
                            "year": "1037"
                          },
                          "startingNotes": {
                            "idNames": [
                              "ushayran",
                              "yegah"
                            ],
                            "displayNames": [
                              "ʿushayrān",
                              "yegāh"
                            ]
                          },
                          "stats": {
                            "numberOfPitchClassesSingleOctave": 17
                          },
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "49"
                            }
                          ]
                        },
                        {
                          "tuningSystem": {
                            "id": "alfarabi_950g",
                            "idName": "alfarabi_950g",
                            "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone",
                            "version": "2025-10-18T19:42:23.643Z",
                            "year": "950g"
                          },
                          "startingNotes": {
                            "idNames": [
                              "ushayran",
                              "yegah"
                            ],
                            "displayNames": [
                              "ʿushayrān",
                              "yegāh"
                            ]
                          },
                          "stats": {
                            "numberOfPitchClassesSingleOctave": 27
                          },
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "50"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "arabic": {
                    "summary": "Arabic display names (includeArabic=true)",
                    "value": {
                      "count": 35,
                      "data": [
                        {
                          "tuningSystem": {
                            "id": "ibnsina_1037",
                            "idName": "ibnsina_1037",
                            "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                            "displayNameAr": "ابن سينا (1037) 7-Fret Oud 17-Tone",
                            "version": "2025-10-18T19:42:23.643Z",
                            "year": "1037"
                          },
                          "startingNotes": {
                            "idNames": [
                              "ushayran",
                              "yegah"
                            ],
                            "displayNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "displayNamesAr": [
                              "عشيران",
                              "يگاه"
                            ]
                          },
                          "stats": {
                            "numberOfPitchClassesSingleOctave": 17
                          },
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "49"
                            }
                          ]
                        },
                        {
                          "tuningSystem": {
                            "id": "alfarabi_950g",
                            "idName": "alfarabi_950g",
                            "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone",
                            "displayNameAr": "الفارابي (950g) تنغيم العود الأول (الديوان الأول الكامل) ٢٧-نغمة",
                            "version": "2025-10-18T19:42:23.643Z",
                            "year": "950g"
                          },
                          "startingNotes": {
                            "idNames": [
                              "ushayran",
                              "yegah"
                            ],
                            "displayNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "displayNamesAr": [
                              "عشيران",
                              "يگاه"
                            ]
                          },
                          "stats": {
                            "numberOfPitchClassesSingleOctave": 27
                          },
                          "sources": [
                            {
                              "sourceId": "al-Shawwa-(1946)",
                              "page": "50"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tuning-systems/{id}/{startingNote}/pitch-classes": {
      "get": {
        "tags": [
          "Tuning Systems"
        ],
        "summary": "Get Tuning System Details",
        "description": "Get Tuning System Details - Returns all pitch classes for a specific tuning system and starting note.\n\nThis endpoint is essential for tuning system operations, providing comprehensive pitch class data\nacross all octaves with full formatting options.\n",
        "operationId": "getTuningSystemPitchClasses",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tuning system identifier",
            "schema": {
              "type": "string"
            },
            "example": "cairocongresstuningcommittee_1929"
          },
          {
            "name": "startingNote",
            "in": "path",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": false,
            "description": "Pitch class data format. When omitted, defaults to \"all\".\n- `all` returns all available fields including englishName, solfege, abjadName, fraction, cents, decimalRatio, stringLength, frequency, fretDivision, midiNoteDecimal, midiNotePlusCentsDeviation, centsDeviation, ipnReferenceNoteName\n- Use a specific value to return only that field plus minimal identifiers\n",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "englishName",
                "solfege",
                "fraction",
                "cents",
                "decimalRatio",
                "stringLength",
                "frequency",
                "abjadName",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "centsDeviation",
                "referenceNoteName"
              ]
            },
            "default": "all",
            "example": "all"
          },
          {
            "name": "octave",
            "in": "query",
            "required": false,
            "description": "Filter by octave number. Use \"all\" to return pitch classes from all octaves (default).\nUse a specific octave number (0, 1, 2, 3) to filter to that octave only.\n",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "0",
                "1",
                "2",
                "3"
              ]
            },
            "default": "all",
            "example": "all"
          },
          {
            "name": "includeSources",
            "in": "query",
            "required": false,
            "description": "Include bibliographic source references (sourceId and page) for the tuning system",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "default": "false",
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Tuning system pitch classes retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tuningSystem",
                    "startingNotes",
                    "selectedStartingNote",
                    "stats",
                    "pitchClasses",
                    "context",
                    "links"
                  ],
                  "properties": {
                    "tuningSystem": {
                      "$ref": "#/components/schemas/EntityRef"
                    },
                    "startingNotes": {
                      "type": "object",
                      "properties": {
                        "idNames": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "displayNames": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "selectedStartingNote": {
                      "type": "object",
                      "properties": {
                        "idName": {
                          "type": "string"
                        },
                        "displayName": {
                          "type": "string"
                        }
                      }
                    },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "totalPitchClasses": {
                          "type": "integer"
                        },
                        "numberOfPitchClassesSingleOctave": {
                          "type": "integer"
                        },
                        "referenceFrequency": {
                          "type": "number"
                        },
                        "octaves": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "pitchClasses": {
                      "type": "array",
                      "description": "Array of formatted pitch class data. Fields vary by pitchClassDataType.\nWhen pitchClassDataType=all, each item includes: pitchClassIndex, octave, noteName, noteNameDisplay, englishName, solfege, abjadName, fraction, cents, decimalRatio, stringLength, frequency, fretDivision, midiNoteDecimal, midiNotePlusCentsDeviation, centsDeviation, ipnReferenceNoteName.\n",
                      "items": {
                        "type": "object",
                        "description": "Pitch class object; properties depend on pitchClassDataType",
                        "properties": {
                          "pitchClassIndex": {
                            "type": "integer",
                            "description": "Index of the pitch class within the tuning system"
                          },
                          "octave": {
                            "type": "integer",
                            "description": "Octave number (0-3)"
                          },
                          "noteName": {
                            "type": "string",
                            "description": "URL-safe note name identifier"
                          },
                          "noteNameDisplay": {
                            "type": "string",
                            "description": "Display form of the note name"
                          },
                          "englishName": {
                            "type": "string",
                            "description": "International Pitch Notation name (e.g. G3, Bb3). Included when pitchClassDataType is all or englishName."
                          },
                          "solfege": {
                            "type": "string",
                            "description": "Fixed-do solfege syllable (Do, Re, Mi, Fa, Sol, La, Si) with accidentals and octave appended (no spaces, e.g. Mi-b3, Sol2). Included when pitchClassDataType is all or solfege."
                          },
                          "abjadName": {
                            "type": "string",
                            "description": "Arabic abjad name. Included when pitchClassDataType is all or abjadName."
                          },
                          "fraction": {
                            "type": "string",
                            "description": "Frequency ratio as fraction. Included when pitchClassDataType is all or fraction."
                          },
                          "cents": {
                            "type": "number",
                            "description": "Pitch in cents. Included when pitchClassDataType is all or cents."
                          },
                          "decimalRatio": {
                            "type": "number",
                            "description": "Frequency ratio as decimal. Included when pitchClassDataType is all or decimalRatio."
                          },
                          "stringLength": {
                            "type": "number",
                            "description": "Relative string length. Included when pitchClassDataType is all or stringLength."
                          },
                          "frequency": {
                            "type": "number",
                            "description": "Frequency in Hz. Included when pitchClassDataType is all or frequency."
                          },
                          "fretDivision": {
                            "type": "string",
                            "description": "Fret position. Included when pitchClassDataType is all or fretDivision."
                          },
                          "midiNoteDecimal": {
                            "type": "number",
                            "description": "MIDI note with fractional precision. Included when pitchClassDataType is all or midiNoteNumber."
                          },
                          "midiNotePlusCentsDeviation": {
                            "type": "string",
                            "description": "IPN reference note with cents deviation. Included when pitchClassDataType is all or midiNoteDeviation."
                          },
                          "centsDeviation": {
                            "type": "number",
                            "description": "Deviation in cents from nearest equal-tempered pitch. Included when pitchClassDataType is all or centsDeviation."
                          },
                          "ipnReferenceNoteName": {
                            "type": "string",
                            "description": "IPN reference note name. Included when pitchClassDataType is all or referenceNoteName."
                          }
                        }
                      }
                    },
                    "sources": {
                      "type": "array",
                      "description": "Bibliographic source references for this tuning system",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sourceId": {
                            "type": "string",
                            "description": "URL-safe source identifier",
                            "example": "al-Shawwa-(1946)"
                          },
                          "page": {
                            "type": "string",
                            "description": "Page number or range where the tuning system is documented",
                            "example": "49"
                          }
                        }
                      }
                    },
                    "context": {
                      "type": "object",
                      "properties": {
                        "pitchClassDataType": {
                          "type": "string"
                        },
                        "octave": {
                          "type": "string",
                          "nullable": true,
                          "description": "\"all\" if all octaves, or specific octave number"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        },
                        "tuningSystem": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/{idName}/transpositions": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "List transpositions for a maqām",
        "description": "List all available transposition options for a maqām within a specific tuning system and starting note.\n\nReturns all tonic transpositions that are feasible under the tuning system across all octaves.\n",
        "operationId": "listMaqamTranspositions",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe maqām identifier",
            "schema": {
              "type": "string"
            },
            "example": "maqam_hijaz"
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899')",
            "schema": {
              "type": "string"
            },
            "example": "alsabbagh_1954"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Transpositions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "maqam": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Numeric identifier for the maqām"
                        },
                        "idName": {
                          "type": "string",
                          "description": "URL-safe identifier for the maqām"
                        },
                        "displayName": {
                          "type": "string",
                          "description": "Display name with diacritics (e.g., \"Maqam Rāst\")"
                        },
                        "version": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of last modification"
                        }
                      }
                    },
                    "context": {
                      "type": "object",
                      "properties": {
                        "tuningSystem": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Tuning system identifier"
                            },
                            "displayName": {
                              "type": "string",
                              "description": "Display name formatted as \"Creator (Year) Title\" (e.g., \"Ibn Sīnā (1037) 7-Fret Oud 17-Tone\")"
                            },
                            "version": {
                              "type": "string",
                              "description": "ISO 8601 timestamp of last modification"
                            }
                          }
                        },
                        "startingNote": {
                          "type": "string",
                          "description": "Tuning system starting note name with diacritics"
                        },
                        "pitchClassesInOctave": {
                          "type": "integer",
                          "description": "Number of pitch classes in a single octave (not counting adjacent octaves)"
                        }
                      }
                    },
                    "transpositions": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total number of transpositions available"
                        },
                        "list": {
                          "type": "array",
                          "description": "Array of transposition options",
                          "items": {
                            "type": "object",
                            "properties": {
                              "tonicId": {
                                "type": "string",
                                "description": "URL-safe tonic note identifier"
                              },
                              "tonicDisplay": {
                                "type": "string",
                                "description": "Tonic note name with diacritics"
                              },
                              "pitchClassIndex": {
                                "type": "integer",
                                "description": "Index of the tonic pitch class in the tuning system"
                              },
                              "octave": {
                                "type": "integer",
                                "description": "Octave number of the tonic (1 = primary octave, 2 = octave above, etc.)"
                              },
                              "dataHref": {
                                "type": "string",
                                "description": "URL to retrieve full maqām data for this transposition"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Maqām or tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/{idName}/compare": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "Compare maqām data across multiple tuning systems",
        "description": "Compare comprehensive maqām data across multiple tuning systems and starting note configurations in a single request.\n\nReturns comprehensive data similar to `/maqamat/{idName}` but without modulations and suyur. Each comparison includes:\n- Pitch class data (ascending and descending sequences)\n- Optional interval data\n- Ajnās (constituent melodic structures) mapping\n- Maqām metadata (family classification, tonic, transposition status)\n- Context information (tuning system, starting note, reference frequency)\n\nThis endpoint is ideal for comparative musicological analysis across different historical tuning systems.\n",
        "operationId": "compareMaqam",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe maqām identifier",
            "schema": {
              "type": "string"
            },
            "example": "maqam_bayyat"
          },
          {
            "name": "tuningSystems",
            "in": "query",
            "required": true,
            "description": "Comma-separated tuning system IDs. All tuning systems will use the same starting note and optional transposition.\n",
            "schema": {
              "type": "string"
            },
            "example": "cairocongresstuningcommittee_1929,alsabbagh_1954"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Starting note name (URL-safe, diacritics-insensitive) - applies to all tuning systems. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": true,
            "description": "Output format for pitch class data",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "englishName",
                "fraction",
                "cents",
                "decimalRatio",
                "stringLength",
                "frequency",
                "abjadName",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "centsDeviation",
                "referenceNoteName"
              ]
            },
            "default": "cents",
            "example": "cents"
          },
          {
            "name": "includeIntervals",
            "in": "query",
            "required": false,
            "description": "Include interval data between pitch classes",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "transposeTo",
            "in": "query",
            "required": false,
            "description": "Transpose to specific tonic note (applies to all tuning systems)",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "maqam",
                    "comparisons",
                    "meta"
                  ],
                  "properties": {
                    "maqam": {
                      "type": "object",
                      "description": "Original maqām identifier information",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Numeric identifier for the maqām"
                        },
                        "idName": {
                          "type": "string",
                          "description": "URL-safe identifier for the maqām"
                        },
                        "displayName": {
                          "type": "string",
                          "description": "Display name with diacritics"
                        },
                        "version": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of last modification"
                        }
                      }
                    },
                    "comparisons": {
                      "type": "array",
                      "description": "Array of comparison results (one per configuration)",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tuningSystem": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "Tuning system identifier"
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Display name formatted as \"Creator (Year) Title\""
                              },
                              "version": {
                                "type": "string",
                                "description": "ISO 8601 timestamp of last modification"
                              }
                            }
                          },
                          "maqam": {
                            "type": "object",
                            "description": "Maqām data for this comparison (may include transposition info)",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "idName": {
                                "type": "string"
                              },
                              "displayName": {
                                "type": "string"
                              },
                              "version": {
                                "type": "string"
                              },
                              "tonicId": {
                                "type": "string",
                                "description": "URL-safe tonic note identifier"
                              },
                              "tonicName": {
                                "type": "string",
                                "description": "Tonic note name with diacritics"
                              },
                              "transposition": {
                                "type": "boolean",
                                "description": "Whether this is a transposition from the original tonic"
                              },
                              "originalTonicId": {
                                "type": "string",
                                "description": "Original tonic identifier (present only if transposed)"
                              },
                              "originalTonicDisplay": {
                                "type": "string",
                                "description": "Original tonic name (present only if transposed)"
                              },
                              "familyId": {
                                "type": "string",
                                "description": "URL-safe maqām family identifier"
                              },
                              "familyDisplay": {
                                "type": "string",
                                "description": "Maqām family name with diacritics"
                              },
                              "numberOfPitchClasses": {
                                "type": "integer",
                                "description": "Number of pitch classes in this maqām"
                              },
                              "isOctaveRepeating": {
                                "type": "boolean",
                                "description": "Whether the maqām structure repeats within an octave"
                              },
                              "pitchClassDataType": {
                                "type": "string",
                                "description": "Format used for pitch class data"
                              },
                              "includeIntervals": {
                                "type": "boolean",
                                "description": "Whether intervals are included"
                              }
                            }
                          },
                          "context": {
                            "type": "object",
                            "properties": {
                              "tuningSystem": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "description": "Tuning system identifier"
                                  }
                                }
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Display name formatted as \"Creator (Year) Title\""
                              },
                              "version": {
                                "type": "string",
                                "description": "ISO 8601 timestamp of last modification"
                              },
                              "numberOfPitchClassesSingleOctave": {
                                "type": "integer",
                                "description": "Number of pitch classes in one octave of the selected tuning system (from tuning system's original pitch class values)"
                              },
                              "startingNoteName": {
                                "type": "string",
                                "description": "Starting note name (URL-safe)"
                              },
                              "referenceFrequency": {
                                "type": "number",
                                "description": "Reference frequency in Hz associated with the starting note name (falls back to tuning system default if not specified for this note)"
                              }
                            }
                          },
                          "pitchData": {
                            "type": "object",
                            "properties": {
                              "ascending": {
                                "type": "array",
                                "description": "Ascending pitch class sequence",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "descending": {
                                "type": "array",
                                "description": "Descending pitch class sequence",
                                "items": {
                                  "type": "object"
                                }
                              }
                            }
                          },
                          "intervals": {
                            "type": "object",
                            "description": "Interval data (present only if includeIntervals=true)",
                            "properties": {
                              "ascending": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "descending": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              }
                            }
                          },
                          "ajnas": {
                            "type": "object",
                            "description": "Ajnās mapping for each note position",
                            "properties": {
                              "ascending": {
                                "type": "object",
                                "description": "Ascending ajnās mapping (note name to jins entity object or null)"
                              },
                              "descending": {
                                "type": "object",
                                "description": "Descending ajnās mapping (note name to jins entity object or null)"
                              }
                            }
                          },
                          "error": {
                            "type": "string",
                            "description": "Error message if this comparison failed"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "totalComparisons": {
                          "type": "integer",
                          "description": "Total number of comparisons requested"
                        },
                        "successfulComparisons": {
                          "type": "integer",
                          "description": "Number of successful comparisons"
                        },
                        "failedComparisons": {
                          "type": "integer",
                          "description": "Number of failed comparisons"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "twoTuningSystems": {
                    "summary": "Compare across two tuning systems",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "Maqam Rāst",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "comparisons": [
                        {
                          "maqam": {
                            "id": "1",
                            "idName": "maqam_rast",
                            "displayName": "Maqam Rāst",
                            "version": "2025-10-18T19:41:17.132Z",
                            "tonicId": "rast",
                            "tonicDisplay": "rāst",
                            "transposition": false,
                            "familyId": "rast",
                            "familyDisplay": "Rāst",
                            "numberOfPitchClasses": 7,
                            "isOctaveRepeating": true,
                            "pitchClassDataType": "cents",
                            "includeIntervals": true
                          },
                          "context": {
                            "tuningSystem": {
                              "id": "meshshaqa_1899",
                              "displayName": "Meshshāqa (1899) Arabic Octave According to the Modernists",
                              "version": "2025-10-18T19:41:17.132Z",
                              "numberOfPitchClassesSingleOctave": 24,
                              "tuningSystemStartingNoteNames": [
                                "yegāh"
                              ],
                              "tuningSystemStartingNoteNamesIds": [
                                "yegah"
                              ],
                              "startingNoteName": "yegah",
                              "referenceFrequency": 97.999
                            }
                          },
                          "pitchData": {
                            "ascending": [
                              {
                                "pitchClassIndex": 0,
                                "octave": 1,
                                "scaleDegree": "I",
                                "noteName": "rast",
                                "noteNameDisplay": "rāst",
                                "cents": 0
                              },
                              {
                                "pitchClassIndex": 1,
                                "octave": 1,
                                "scaleDegree": "II",
                                "noteName": "dugah",
                                "noteNameDisplay": "dūgāh",
                                "cents": 204
                              }
                            ]
                          },
                          "intervals": {
                            "ascending": [
                              {
                                "cents": 204
                              }
                            ]
                          },
                          "ajnas": {
                            "ascending": {
                              "rāst": {
                                "id": "1",
                                "idName": "jins_rast",
                                "displayName": "Jins Rāst"
                              },
                              "dūgāh": null
                            }
                          }
                        },
                        {
                          "maqam": {
                            "id": "1",
                            "idName": "maqam_rast",
                            "displayName": "Maqam Rāst",
                            "version": "2025-10-18T19:41:17.132Z",
                            "tonicId": "rast",
                            "tonicName": "rāst",
                            "transposition": false,
                            "maqamFamilyId": "rast",
                            "maqamFamilyDisplayName": "Rāst",
                            "numberOfPitchClasses": 7,
                            "isOctaveRepeating": true,
                            "pitchClassDataType": "cents",
                            "includeIntervals": true
                          },
                          "context": {
                            "tuningSystem": {
                              "id": "ibnsina_1037",
                              "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                              "version": "2025-10-18T19:41:17.132Z",
                              "numberOfPitchClassesSingleOctave": 17,
                              "startingNoteName": "yegah",
                              "referenceFrequency": 97.999
                            }
                          },
                          "pitchData": {
                            "ascending": [
                              {
                                "pitchClassIndex": 0,
                                "octave": 1,
                                "scaleDegree": "I",
                                "noteName": "rast",
                                "noteNameDisplay": "rāst",
                                "cents": 0
                              },
                              {
                                "pitchClassIndex": 1,
                                "octave": 1,
                                "scaleDegree": "II",
                                "noteName": "dugah",
                                "noteNameDisplay": "dūgāh",
                                "cents": 211.7
                              }
                            ]
                          },
                          "intervals": {
                            "ascending": [
                              {
                                "cents": 211.7
                              }
                            ]
                          },
                          "ajnas": {
                            "ascending": {
                              "rāst": {
                                "id": "1",
                                "idName": "jins_rast",
                                "displayName": "Jins Rāst"
                              },
                              "dūgāh": null
                            }
                          }
                        }
                      ],
                      "meta": {
                        "totalComparisons": 2,
                        "successfulComparisons": 2,
                        "failedComparisons": 0
                      }
                    }
                  },
                  "withTransposition": {
                    "summary": "Compare with transposition",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "Maqam Rāst",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "comparisons": [
                        {
                          "maqam": {
                            "id": "1",
                            "idName": "maqam_rast_al-nawa",
                            "displayName": "Maqam Rāst al-Nawā",
                            "version": "2025-10-18T19:41:17.132Z",
                            "tonicId": "nawa",
                            "tonicName": "nawā",
                            "transposition": true,
                            "originalTonicId": "rast",
                            "originalTonicName": "rāst",
                            "maqamFamilyId": "rast",
                            "maqamFamilyDisplayName": "Rāst",
                            "numberOfPitchClasses": 7,
                            "isOctaveRepeating": true,
                            "pitchClassDataType": "cents",
                            "includeIntervals": false
                          },
                          "context": {
                            "tuningSystem": {
                              "id": "ibnsina_1037",
                              "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                              "version": "2025-10-18T19:41:17.132Z",
                              "numberOfPitchClassesSingleOctave": 17,
                              "startingNoteName": "yegah",
                              "referenceFrequency": 97.999
                            }
                          },
                          "pitchData": {
                            "ascending": [
                              {
                                "pitchClassIndex": 3,
                                "octave": 1,
                                "scaleDegree": "I",
                                "noteName": "nawa",
                                "noteNameDisplay": "nawā",
                                "cents": 498
                              }
                            ]
                          },
                          "ajnas": {
                            "ascending": {
                              "nawā": {
                                "id": "1",
                                "idName": "jins_rast",
                                "displayName": "Jins Rāst"
                              }
                            }
                          }
                        }
                      ],
                      "meta": {
                        "totalComparisons": 1,
                        "successfulComparisons": 1,
                        "failedComparisons": 0
                      }
                    }
                  },
                  "withErrors": {
                    "summary": "Comparison with some failures",
                    "value": {
                      "maqam": {
                        "id": "1",
                        "idName": "maqam_rast",
                        "displayName": "Maqam Rāst",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "comparisons": [
                        {
                          "maqam": {
                            "id": "1",
                            "idName": "maqam_rast",
                            "displayName": "Maqam Rāst",
                            "version": "2025-10-18T19:41:17.132Z",
                            "tonicId": "rast",
                            "tonicName": "rāst",
                            "transposition": false,
                            "maqamFamilyId": "rast",
                            "maqamFamilyDisplayName": "Rāst",
                            "numberOfPitchClasses": 7,
                            "isOctaveRepeating": true,
                            "pitchClassDataType": "cents",
                            "includeIntervals": false
                          },
                          "context": {
                            "tuningSystem": {
                              "id": "ibnsina_1037",
                              "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                              "version": "2025-10-18T19:41:17.132Z",
                              "numberOfPitchClassesSingleOctave": 17,
                              "startingNoteName": "yegah",
                              "referenceFrequency": 97.999
                            }
                          },
                          "pitchData": {
                            "ascending": [
                              {
                                "pitchClassIndex": 0,
                                "octave": 1,
                                "scaleDegree": "I",
                                "noteName": "rast",
                                "noteNameDisplay": "rāst",
                                "cents": 0
                              }
                            ]
                          },
                          "ajnas": {
                            "ascending": {
                              "rāst": {
                                "id": "1",
                                "idName": "jins_rast",
                                "displayName": "Jins Rāst"
                              }
                            }
                          }
                        },
                        {
                          "error": "Tuning system 'InvalidSystem' not found"
                        }
                      ],
                      "meta": {
                        "totalComparisons": 2,
                        "successfulComparisons": 1,
                        "failedComparisons": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingTuningSystems": {
                    "summary": "Missing tuningSystems parameter",
                    "value": {
                      "error": "tuningSystems parameter is required",
                      "message": "Provide comma-separated tuning system IDs",
                      "hint": "Format: ?tuningSystems=ibnsina_1037,alfarabi_950g",
                      "example": "/api/maqamat/maqam_bayyat/compare?tuningSystems=cairocongresstuningcommittee_1929,alsabbagh_1954&startingNote=rast&pitchClassDataType=cents"
                    }
                  },
                  "missingStartingNote": {
                    "summary": "Missing startingNote parameter",
                    "value": {
                      "error": "startingNote parameter is required",
                      "message": "A starting note must be specified for all tuning systems",
                      "hint": "Add &startingNote=yegah to your request"
                    }
                  },
                  "invalidIntervals": {
                    "summary": "Invalid includeIntervals parameter",
                    "value": {
                      "error": "Invalid parameter: includeIntervals",
                      "message": "The 'includeIntervals' parameter must be 'true' or 'false'.",
                      "validOptions": [
                        "true",
                        "false"
                      ],
                      "hint": "Use ?includeIntervals=true or ?includeIntervals=false"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Maqām not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Maqām 'maqam_invalid' not found",
                  "hint": "Use /api/maqamat to see all available maqāmāt"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/classification/12-pitch-class-sets": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "Classify maqāmāt by 12-pitch-class sets",
        "description": "Groups maqāmāt according to sets of 12 pitch classes suitable for MIDI keyboard tuning\nand Scala file export. Each set is created by merging pitch classes from the specified\ntuning system with alkindi_874 filler pitch classes, based on matching IPN reference\nnote names.\n\n**Critical Design Principles:**\n- **Octave Alignment**: Both the maqām tuning system and alkindi_874 use the same\n  `startingNote` to ensure octaves align correctly\n- **Chromatic Order**: Each set contains exactly 12 pitch classes ordered chromatically\n  starting from the maqām's tonic (e.g., C, C#, D, D#... for Rāst)\n- **Arabic Musicological Logic**: IPN references respect Arabic maqām theory where\n  microtonal modifiers indicate what the pitch is a variant OF, not mathematical proximity\n  to 12-EDO semitones\n- **Direct Tuning System Values**: All cent values come directly from tuning systems\n  without post-processing or calculation\n\n**The Algorithm:**\n1. Loads pitch classes from both the specified tuning system and alkindi_874 using\n   the same `startingNote`\n2. For each maqām transposition:\n   - Extracts IPN reference note names from ascending and descending sequences\n   - Replaces matching pitch classes in al-Kindi base (ascending takes priority, then descending)\n   - Selects pitch classes from correct octaves to ensure ascending chromatic order\n   - Orders the 12 pitch classes chromatically starting from the maqām's tonic\n3. Groups compatible maqāmāt together\n4. Names each group after the source maqām (e.g., \"maqām rāst set\")\n\n**Compatibility:**\n- Maqāmāt with duplicate IPN references (same IPN appearing with different pitch values)\n  are marked as incompatible and cannot form valid 12-pitch-class sets\n- Compatible maqāmāt can be performed entirely within a single 12-pitch-class set\n\n**Output Format:**\n- Pitch classes ordered chromatically (C, C#, D, D#, E, F, F#, G, G#, A, A#, B)\n- Starting from the maqām's tonic (default) OR from IPN \"C\" (if `startSetFromC=true`)\n- Relative cents from 0 (reference note) to ~1050-1200 (octave)\n- `maqamTonic` field indicates the actual maqām tonic position and note name\n- Suitable for MIDI keyboard tuning and Scala (.scl) file generation\n\n**Filtering Options:**\n- Use `setId` to retrieve a specific set and its compatible maqāmāt\n- Use `maqamId` to find all sets containing a specific maqām\n",
        "operationId": "classifyMaqamat12PitchClassSets",
        "parameters": [
          {
            "name": "tuningSystem",
            "in": "query",
            "description": "Tuning system ID for maqāmāt (default: cairocongresstuningcommittee_1929)",
            "schema": {
              "type": "string",
              "default": "cairocongresstuningcommittee_1929"
            },
            "example": "cairocongresstuningcommittee_1929"
          },
          {
            "name": "startingNote",
            "in": "query",
            "description": "Starting note for both the maqām tuning system and alkindi_874 (default: yegah).\nIMPORTANT: Both tuning systems must use the same starting note to ensure octaves align\ncorrectly and pitch classes can be properly selected from matching octaves.\n\nUse `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string",
              "default": "yegah"
            },
            "example": "yegah"
          },
          {
            "name": "centsTolerance",
            "in": "query",
            "description": "Tolerance in cents for pitch class comparison (default: 5)",
            "schema": {
              "type": "number",
              "default": 5,
              "minimum": 0
            },
            "example": 5
          },
          {
            "name": "includeIncompatible",
            "in": "query",
            "description": "Include maqāmāt that cannot form valid 12-pitch-class sets",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "startSetFromC",
            "in": "query",
            "description": "Start pitch class set from IPN reference \"C\" (degree 0) instead of from the maqām's tonic.\nWhen `true`, the set is reordered to start from C at 0.00 cents (relative), making it\ndirectly compatible with Scala (.scl) file format which maps degree 0 to middle C by default.\n\n**Technical Implementation:**\n1. **Octave Selection**: For maqāmāt starting mid-octave (e.g., D), pitch classes before the tonic in chromatic order (C, C#) are taken from octave 1, while those at or after the tonic use their original octaves\n2. **Array Rotation**: The 12 pitch classes are rotated to place C first\n3. **Relative Cents**: Calculated from C (0.00 cents), with octave wrap-around handling (negative values + 1200)\n4. **Note Names**: Arabic note names follow the NoteName model's octave conventions (e.g., C octave 1 = rāst, C octave 2 = kurdān)\n5. **Tonic Tracking**: The `maqamTonic` field indicates the actual maqām tonic's IPN, note names, and position in the reordered set\n\n**Use Cases:**\n- `false` (default): For understanding maqām structure starting from its tonic\n- `true`: For Scala .scl export (no .kbm file needed) or MIDI keyboard mapping where C = degree 0\n\n**Example:**\n- Maqām ḥijāz (tonic D/dūgāh at 702.13 cents):\n  - Default mode: D at position 0 (0.00 cents relative)\n  - Scala mode: C (rāst, 498.04 cents) at position 0 (0.00 cents relative), D at position 2 (204.08 cents relative)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": false,
            "description": "Controls which pitch class data fields are returned in the response.\n\n**Available Options:**\n- `all`: Returns all available pitch class data fields\n- `englishName`: English note name with octave (e.g., \"D2\", \"E-b3\")\n- `fraction`: Frequency ratio as a fraction string\n- `cents`: Absolute cents value from the tuning system\n- `decimalRatio`: Frequency ratio as decimal number\n- `stringLength`: String length for oud/qanun (if available)\n- `frequency`: Frequency in Hz\n- `abjadName`: Arabic abjad notation (if available)\n- `fretDivision`: Fret position for oud (if available)\n- `midiNoteNumber`: MIDI note number as decimal\n- `midiNoteDeviation`: MIDI note with cents deviation string\n- `centsDeviation`: Cents deviation from 12-EDO\n- `referenceNoteName`: IPN reference note name\n- `relativeCents`: Cents relative to the first pitch class (0.00 for tonic or C)\n\n**Default Behavior (parameter omitted):**\n- Returns minimal fields: `ipnReferenceNoteName`, `noteName`, `relativeCents`, `octave`\n\n**Example:**\n- `?pitchClassDataType=cents` returns only IPN, note name, and cents values\n- `?pitchClassDataType=all` returns all available data fields\n",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "abjadName",
                "englishName",
                "solfege",
                "fraction",
                "cents",
                "centsDeviation",
                "decimalRatio",
                "stringLength",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "frequency",
                "referenceNoteName",
                "relativeCents"
              ]
            },
            "example": "cents"
          },
          {
            "name": "setId",
            "in": "query",
            "description": "Filter by specific set ID to retrieve that set and its compatible maqāmāt (e.g., 'maqam_rast_set')",
            "schema": {
              "type": "string"
            },
            "example": "maqam_rast_set"
          },
          {
            "name": "maqamId",
            "in": "query",
            "description": "Filter by maqām ID to find all sets containing that maqām (e.g., 'maqam_rast')",
            "schema": {
              "type": "string"
            },
            "example": "maqam_rast"
          }
        ],
        "responses": {
          "200": {
            "description": "Classification results with sets and compatible maqāmāt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "array",
                      "description": "Summary of each set with compatible maqāmāt names",
                      "items": {
                        "type": "object",
                        "properties": {
                          "setName": {
                            "type": "string",
                            "example": "maqām rast set"
                          },
                          "compatibleMaqamat": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "maqamName": {
                                  "type": "string"
                                },
                                "transpositionName": {
                                  "type": "string"
                                },
                                "isTransposed": {
                                  "type": "boolean"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "statistics": {
                      "type": "object",
                      "description": "Statistics about the classification",
                      "properties": {
                        "totalSets": {
                          "type": "number"
                        },
                        "sets": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "setName": {
                                "type": "string"
                              },
                              "compatibleMaqamatCount": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "totalCompatibleMaqamat": {
                          "type": "number"
                        },
                        "incompatibleMaqamatCount": {
                          "type": "number"
                        }
                      }
                    },
                    "sets": {
                      "type": "array",
                      "description": "Classification sets grouping compatible maqāmāt",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "URL-safe identifier for the set",
                            "example": "maqam_rast_set"
                          },
                          "setIdName": {
                            "type": "string",
                            "description": "Standardized identifier for the set",
                            "example": "maqam_rast_set"
                          },
                          "setDisplayName": {
                            "type": "string",
                            "description": "Display name of the set",
                            "example": "maqām rāst set"
                          },
                          "sourceMaqam": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "sourceTransposition": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "example": "maqām rāst"
                              },
                              "isTransposed": {
                                "type": "boolean",
                                "example": false
                              }
                            }
                          },
                          "pitchClassSet": {
                            "type": "array",
                            "description": "The 12 pitch classes in this set",
                            "items": {
                              "type": "object",
                              "properties": {
                                "ipnReferenceNoteName": {
                                  "type": "string",
                                  "example": "C"
                                },
                                "noteName": {
                                  "type": "string",
                                  "example": "rāst"
                                },
                                "cents": {
                                  "type": "number",
                                  "example": 0
                                },
                                "fraction": {
                                  "type": "string",
                                  "example": "1/1"
                                },
                                "decimalRatio": {
                                  "type": "number",
                                  "example": 1
                                },
                                "frequency": {
                                  "type": "number",
                                  "example": 130.665
                                },
                                "octave": {
                                  "type": "number",
                                  "example": 1
                                }
                              }
                            }
                          },
                          "maqamTonic": {
                            "type": "object",
                            "description": "Information about the actual maqām tonic position in the set",
                            "properties": {
                              "ipnReferenceNoteName": {
                                "type": "string",
                                "description": "IPN reference name of the tonic (e.g., \"C\", \"F\", \"G\"). Uses pitch class equivalent for octave variants (qarār dūgāh → \"D\")",
                                "example": "C"
                              },
                              "noteNameIdName": {
                                "type": "string",
                                "description": "Standardized identifier for the tonic note name (ASCII-safe, URL-friendly)",
                                "example": "rast"
                              },
                              "noteNameDisplayName": {
                                "type": "string",
                                "description": "Display name of the tonic note (with diacritics)",
                                "example": "rāst"
                              },
                              "positionInSet": {
                                "type": "number",
                                "description": "Index position (0-11) of the maqām tonic in the pitch class set.\n- In default mode (startSetFromC=false): Always 0\n- In Scala mode (startSetFromC=true): Varies based on tonic (e.g., 2 for D, 5 for F)\n- Octave equivalents (qarār dūgāh, muḥayyar) map to same position as their pitch class (D → position 2)\n",
                                "example": 0
                              }
                            }
                          },
                          "compatibleMaqamat": {
                            "type": "array",
                            "description": "Maqāmāt compatible with this set",
                            "items": {
                              "type": "object",
                              "properties": {
                                "maqamIdName": {
                                  "type": "string",
                                  "description": "Standardized identifier for the maqām transposition",
                                  "example": "maqam_rast"
                                },
                                "maqamDisplayName": {
                                  "type": "string",
                                  "description": "Display name of the maqām transposition",
                                  "example": "maqām rāst"
                                },
                                "isTransposed": {
                                  "type": "boolean",
                                  "description": "Whether this is a transposition of the base maqām"
                                }
                              }
                            }
                          },
                          "compatibleMaqamatCount": {
                            "type": "number",
                            "description": "Number of compatible maqāmāt in this set"
                          }
                        }
                      }
                    },
                    "totalSets": {
                      "type": "number",
                      "description": "Total number of classification sets"
                    },
                    "totalCompatibleMaqamat": {
                      "type": "number",
                      "description": "Total number of compatible maqām transpositions across all sets"
                    },
                    "incompatibleMaqamat": {
                      "type": "array",
                      "description": "Maqāmāt that cannot form valid 12-pitch-class sets",
                      "items": {
                        "type": "object",
                        "properties": {
                          "maqam": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "transposition": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "isTransposed": {
                                "type": "boolean"
                              }
                            }
                          },
                          "reason": {
                            "type": "string",
                            "example": "duplicate_ipn_reference"
                          }
                        }
                      }
                    },
                    "incompatibleMaqamatCount": {
                      "type": "number",
                      "description": "Number of incompatible maqāmāt"
                    },
                    "parameters": {
                      "type": "object",
                      "description": "Parameters used for classification",
                      "properties": {
                        "tuningSystem": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            }
                          }
                        },
                        "startingNote": {
                          "type": "object",
                          "properties": {
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            }
                          }
                        },
                        "alKindiTuningSystem": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            }
                          }
                        },
                        "alKindiStartingNote": {
                          "type": "object",
                          "properties": {
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            }
                          }
                        },
                        "centsTolerance": {
                          "type": "number"
                        },
                        "startSetFromC": {
                          "type": "boolean",
                          "description": "Whether the set starts from IPN \"C\" (Scala mode) or from the maqām tonic (default)",
                          "example": false
                        },
                        "setId": {
                          "type": "string",
                          "nullable": true,
                          "description": "Set ID filter if applied",
                          "example": "maqam_rast_set"
                        },
                        "maqamId": {
                          "type": "string",
                          "nullable": true,
                          "description": "Maqām ID filter if applied",
                          "example": "maqam_rast"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "default": {
                    "summary": "Default response",
                    "value": {
                      "summary": [
                        {
                          "setIdName": "maqam_rast_set",
                          "setDisplayName": "maqām rāst set",
                          "compatibleMaqamat": [
                            {
                              "maqamIdName": "maqam_rast",
                              "maqamDisplayName": "maqām rāst",
                              "isTransposed": false
                            }
                          ]
                        }
                      ],
                      "statistics": {
                        "totalSets": 1,
                        "sets": [
                          {
                            "setIdName": "maqam_rast_set",
                            "setDisplayName": "maqām rāst set",
                            "compatibleMaqamatCount": 1
                          }
                        ],
                        "totalCompatibleMaqamat": 1,
                        "incompatibleMaqamatCount": 0
                      },
                      "sets": [
                        {
                          "id": "maqam_rast_set",
                          "setIdName": "maqam_rast_set",
                          "setDisplayName": "maqām rāst set",
                          "sourceMaqam": {
                            "id": "1",
                            "idName": "maqam_rast",
                            "displayName": "maqām rāst"
                          },
                          "sourceTransposition": {
                            "idName": "maqam_rast",
                            "displayName": "maqām rāst",
                            "isTransposed": false
                          },
                          "pitchClassSet": [
                            {
                              "ipnReferenceNoteName": "C",
                              "noteName": "rāst",
                              "cents": 0,
                              "fraction": "1/1",
                              "decimalRatio": 1,
                              "frequency": 130.665,
                              "octave": 1
                            }
                          ],
                          "compatibleMaqamat": [
                            {
                              "maqamIdName": "maqam_rast",
                              "maqamDisplayName": "maqām rāst",
                              "isTransposed": false
                            }
                          ],
                          "compatibleMaqamatCount": 1
                        }
                      ],
                      "totalSets": 1,
                      "totalCompatibleMaqamat": 1,
                      "incompatibleMaqamat": [],
                      "incompatibleMaqamatCount": 0,
                      "parameters": {
                        "tuningSystem": {
                          "id": "cairocongresstuningcommittee_1929",
                          "idName": "cairocongresstuningcommittee-1929",
                          "displayName": "Cairo Congress Tuning Committee (1929)"
                        },
                        "startingNote": {
                          "idName": "yegah",
                          "displayName": "yegāh"
                        },
                        "alKindiTuningSystem": {
                          "id": "alkindi_874",
                          "idName": "al-kindi-874",
                          "displayName": "al-Kindī (874)"
                        },
                        "alKindiStartingNote": {
                          "idName": "ushayran",
                          "displayName": "ʿushayrān"
                        },
                        "centsTolerance": 5,
                        "startSetFromC": false
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Set or maqām not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "setNotFound": {
                    "summary": "Set not found",
                    "value": {
                      "error": "Set 'maqam_invalid_set' not found",
                      "hint": "Use ?setId=<set-id> to filter by a specific set (e.g., ?setId=maqam_rast_set)"
                    }
                  },
                  "maqamNotFound": {
                    "summary": "Maqām not found in any set",
                    "value": {
                      "error": "No sets found containing maqam 'maqam_invalid'",
                      "hint": "Use ?maqamId=<maqam-id> to find sets containing a specific maqām (e.g., ?maqamId=maqam_rast)"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/maqamat/classification/maqam-pitch-class-sets": {
      "get": {
        "tags": [
          "Maqāmāt"
        ],
        "summary": "Classify maqāmāt by maqam-based pitch class sets",
        "description": "Groups maqāmāt according to maqam-based pitch class sets. Each set contains all pitch\nclasses from a single source maqam (union of ascending and descending), and identifies\nwhich other maqāmāt can be performed using only those pitch classes.\n\n**Musicological Purpose:**\nAnswers the question: \"Which maqāmāt can be performed using only the pitch classes of\nmaqām X?\" For example, maqām rāst on rāst includes pitch classes that can perform maqām\nbayyāt on dūgāh and maqām segāh on segāh.\n\n**Key Differences from 12-Pitch-Class-Sets:**\n- **No Chromatic Base**: Does not merge with alkindi_874 or chromatic filler pitch classes\n- **Variable Set Sizes**: Sets can contain any number of pitch classes (7, 8, 10, etc.), not fixed at 12\n- **Octave-Equivalent Matching**: Pitch classes in different octaves treated as equivalent (C in octave 1 = C in octave 2)\n- **Single Tuning System**: Uses only the specified tuning system (simpler than 12-pitch-class-sets)\n- **Subset Matching**: Compatible maqāmāt must use subset of source maqam's pitch classes\n\n**Critical Design Principles:**\n- **Octave Equivalence**: IPN references are compared octave-normalized (C at any octave = \"C\")\n- **Union of Melodic Paths**: Includes all pitch classes from both ascending AND descending sequences\n- **Exact Matching**: All pitch classes from a compatible maqām must exist in the source set (within tolerance)\n- **Direct Values**: All cent values come directly from tuning system without calculation\n- **Tahlil Priority**: Base (non-transposed) maqāmāt create canonical sets first, then transpositions\n\n**The Algorithm:**\n1. For each maqām transposition (tahlil first, then transpositions):\n   - Extracts all unique pitch classes from ascending + descending sequences\n   - Groups by IPN reference (octave-equivalent)\n   - Validates no duplicate IPN references with different cents values\n   - Creates a maqam-based pitch class set\n2. For each set, finds compatible maqāmāt:\n   - Checks if all pitch classes needed by candidate maqām exist in source set\n   - Compares cents values within tolerance (octave-normalized)\n   - Marks candidate as compatible if all pitch classes match\n3. Groups compatible maqāmāt together\n4. Names each group after the source maqām (e.g., \"maqām rāst set\")\n\n**Compatibility:**\n- Maqāmāt with duplicate IPN references (same IPN with different cents values when octave-normalized)\n  are marked as incompatible\n- Compatible maqāmāt can be performed entirely using the pitch classes of the source maqām\n- **Minimum Set Size**: Only sets with 2 or more maqāmāt are returned (source + at least one compatible)\n- Sets containing only the source maqām (no compatible maqāmāt) are filtered out\n\n**Output Format:**\n- Sets ordered by number of compatible maqāmāt (descending)\n- Each set includes: source maqām, all pitch classes (in ascending cents order), compatible maqāmāt, pitch class count\n- Pitch classes include: English name, note name, cents, frequency, fraction, etc.\n\n**Filtering Options:**\n- Use `setId` to retrieve a specific set and its compatible maqāmāt\n- Use `maqamId` to find all sets containing a specific maqām\n",
        "operationId": "classifyMaqamatByMaqamPitchClassSets",
        "parameters": [
          {
            "name": "tuningSystem",
            "in": "query",
            "description": "Tuning system ID for all maqāmāt (default: cairocongresstuningcommittee_1929)",
            "schema": {
              "type": "string",
              "default": "cairocongresstuningcommittee_1929"
            },
            "example": "cairocongresstuningcommittee_1929"
          },
          {
            "name": "startingNote",
            "in": "query",
            "description": "Starting note for the tuning system (default: yegah).\n\nUse `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string",
              "default": "yegah"
            },
            "example": "yegah"
          },
          {
            "name": "centsTolerance",
            "in": "query",
            "description": "Tolerance in cents for pitch class comparison (default: 5)",
            "schema": {
              "type": "number",
              "default": 5,
              "minimum": 0
            },
            "example": 5
          },
          {
            "name": "includeIncompatible",
            "in": "query",
            "description": "Include maqāmāt that cannot form valid maqam-based pitch class sets",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includePitchClassData",
            "in": "query",
            "description": "Include pitch class data in the response (default: false).\n\nWhen true: Returns pitchClassSet and pitchClassCount for each set\nWhen false: Omits pitch class data, returning only set metadata and compatible maqamat\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "setId",
            "in": "query",
            "description": "Filter by specific set ID to retrieve that set and its compatible maqāmāt (e.g., 'maqam_rast_set')",
            "schema": {
              "type": "string"
            },
            "example": "maqam_rast_set"
          },
          {
            "name": "maqamId",
            "in": "query",
            "description": "Filter by maqām ID to find all sets containing that maqām (e.g., 'maqam_rast')",
            "schema": {
              "type": "string"
            },
            "example": "maqam_rast"
          }
        ],
        "responses": {
          "200": {
            "description": "Classification results with maqam-based pitch class sets and compatible maqāmāt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statistics": {
                      "type": "object",
                      "description": "Statistics about the classification",
                      "properties": {
                        "totalSets": {
                          "type": "number",
                          "description": "Total number of sets"
                        },
                        "totalCompatibleMaqamat": {
                          "type": "number",
                          "description": "Total number of compatible maqāmāt across all sets"
                        },
                        "incompatibleMaqamatCount": {
                          "type": "number",
                          "description": "Total number of incompatible maqāmāt"
                        },
                        "totalProcessed": {
                          "type": "number",
                          "description": "Total number of maqāmāt processed (compatible + incompatible)"
                        }
                      }
                    },
                    "sets": {
                      "type": "array",
                      "description": "Classification sets grouping compatible maqāmāt",
                      "items": {
                        "type": "object",
                        "properties": {
                          "setIdName": {
                            "type": "string",
                            "description": "Standardized identifier for the set",
                            "example": "maqam_rast_set"
                          },
                          "setDisplayName": {
                            "type": "string",
                            "description": "Display name of the set",
                            "example": "maqām rāst set"
                          },
                          "compatibleMaqamatCount": {
                            "type": "number",
                            "description": "Number of compatible maqāmāt in this set (deduplicated, no octave equivalents)"
                          },
                          "sourceMaqam": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "pitchClassSet": {
                            "type": "array",
                            "description": "All pitch classes in this maqam-based set (variable number, not fixed at 12).\nIncludes all pitch classes from the source maqām's ascending and descending sequences.\nOrdered by ascending cents values (from lowest to highest pitch).\nOnly included when includePitchClassData=true.\n",
                            "items": {
                              "type": "object",
                              "properties": {
                                "englishName": {
                                  "type": "string",
                                  "description": "English note name with octave (e.g., \"C3\", \"D#4\")",
                                  "example": "C3"
                                },
                                "noteName": {
                                  "type": "string",
                                  "description": "Note name from the tuning system",
                                  "example": "rāst"
                                },
                                "cents": {
                                  "type": "number",
                                  "description": "Absolute cents value from the tuning system",
                                  "example": 0
                                },
                                "fraction": {
                                  "type": "string",
                                  "description": "Frequency ratio as fraction",
                                  "example": "1/1"
                                },
                                "decimalRatio": {
                                  "type": "number",
                                  "description": "Frequency ratio as decimal",
                                  "example": 1
                                },
                                "frequency": {
                                  "type": "number",
                                  "description": "Frequency in Hz",
                                  "example": 130.665
                                },
                                "octave": {
                                  "type": "number",
                                  "description": "Octave number",
                                  "example": 1
                                },
                                "noteNameDisplayAr": {
                                  "type": "string",
                                  "description": "Arabic display name (included when includeArabic=true)",
                                  "example": "راست"
                                }
                              }
                            }
                          },
                          "pitchClassCount": {
                            "type": "number",
                            "description": "Number of pitch classes in this set (variable, not fixed at 12).\nOnly included when includePitchClassData=true.\n",
                            "example": 7
                          },
                          "compatibleMaqamat": {
                            "type": "array",
                            "description": "Maqāmāt compatible with this set (can be performed using only these pitch classes).\nOctave equivalents are deduplicated (e.g., maqam rast on rast and maqam rast on muhayyar rast\nare counted as one entry since they share the same base maqam and IPN reference)\n",
                            "items": {
                              "type": "object",
                              "properties": {
                                "maqamIdName": {
                                  "type": "string",
                                  "description": "Standardized identifier for the maqām transposition",
                                  "example": "maqam_rast"
                                },
                                "maqamDisplayName": {
                                  "type": "string",
                                  "description": "Display name of the maqām transposition",
                                  "example": "maqām rāst"
                                },
                                "isTransposed": {
                                  "type": "boolean",
                                  "description": "Whether this is a transposition of the base maqām"
                                },
                                "tonic": {
                                  "type": "object",
                                  "nullable": true,
                                  "description": "Information about the maqām's tonic note",
                                  "properties": {
                                    "ipnReferenceNoteName": {
                                      "type": "string",
                                      "description": "IPN reference name of the tonic (e.g., \"C\", \"D\", \"F\")",
                                      "example": "C"
                                    },
                                    "noteNameIdName": {
                                      "type": "string",
                                      "description": "Standardized identifier for the tonic note name",
                                      "example": "rast"
                                    },
                                    "noteNameDisplayName": {
                                      "type": "string",
                                      "description": "Display name of the tonic note (with diacritics)",
                                      "example": "rāst"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "incompatibleMaqamat": {
                      "type": "array",
                      "description": "Maqāmāt that cannot form valid maqam-based pitch class sets (only included when includeIncompatible=true)",
                      "items": {
                        "type": "object",
                        "properties": {
                          "maqam": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "transposition": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "idName": {
                                "type": "string",
                                "description": "Standardized identifier for the transposition",
                                "example": "maqam_rast"
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Display name of the transposition",
                                "example": "maqām rāst"
                              },
                              "isTransposed": {
                                "type": "boolean",
                                "description": "Whether this is a transposition",
                                "example": false
                              }
                            }
                          },
                          "reason": {
                            "type": "string",
                            "description": "Reason why this maqām is incompatible",
                            "example": "duplicate_ipn_reference"
                          }
                        }
                      }
                    },
                    "incompatibleMaqamatCount": {
                      "type": "number",
                      "description": "Number of incompatible maqāmāt (only included when includeIncompatible=true)"
                    },
                    "parameters": {
                      "type": "object",
                      "description": "Parameters used for classification",
                      "properties": {
                        "tuningSystem": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            }
                          }
                        },
                        "startingNote": {
                          "type": "object",
                          "properties": {
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            }
                          }
                        },
                        "centsTolerance": {
                          "type": "number"
                        },
                        "setId": {
                          "type": "string",
                          "nullable": true,
                          "description": "Set ID filter if applied",
                          "example": "maqam_rast_set"
                        },
                        "maqamId": {
                          "type": "string",
                          "nullable": true,
                          "description": "Maqām ID filter if applied",
                          "example": "maqam_rast"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "default": {
                    "summary": "Default response",
                    "value": {
                      "statistics": {
                        "totalSets": 1,
                        "totalCompatibleMaqamat": 3,
                        "incompatibleMaqamatCount": 0,
                        "totalProcessed": 3
                      },
                      "sets": [
                        {
                          "setIdName": "maqam_rast_set",
                          "setDisplayName": "maqām rāst set",
                          "compatibleMaqamatCount": 3,
                          "sourceMaqam": {
                            "id": "1",
                            "idName": "maqam_rast",
                            "displayName": "maqām rāst"
                          },
                          "pitchClassSet": [
                            {
                              "englishName": "C3",
                              "noteName": "rāst",
                              "cents": 0,
                              "fraction": "1/1",
                              "decimalRatio": 1,
                              "frequency": 130.665,
                              "octave": 1
                            },
                            {
                              "englishName": "D3",
                              "noteName": "dūgāh",
                              "cents": 203.91,
                              "fraction": "9/8",
                              "decimalRatio": 1.125,
                              "frequency": 146.998,
                              "octave": 1
                            },
                            {
                              "englishName": "E3",
                              "noteName": "segāh",
                              "cents": 407.82,
                              "fraction": "81/64",
                              "decimalRatio": 1.266,
                              "frequency": 165.361,
                              "octave": 1
                            }
                          ],
                          "pitchClassCount": 7,
                          "compatibleMaqamat": [
                            {
                              "maqamIdName": "maqam_rast",
                              "maqamDisplayName": "maqām rāst",
                              "isTransposed": false,
                              "tonic": {
                                "ipnReferenceNoteName": "C",
                                "noteNameIdName": "rast",
                                "noteNameDisplayName": "rāst"
                              }
                            },
                            {
                              "maqamIdName": "maqam_bayyat_dugah",
                              "maqamDisplayName": "maqām bayyāt (dūgāh)",
                              "isTransposed": true,
                              "tonic": {
                                "ipnReferenceNoteName": "D",
                                "noteNameIdName": "dugah",
                                "noteNameDisplayName": "dūgāh"
                              }
                            },
                            {
                              "maqamIdName": "maqam_segah_segah",
                              "maqamDisplayName": "maqām segāh (segāh)",
                              "isTransposed": true,
                              "tonic": {
                                "ipnReferenceNoteName": "E",
                                "noteNameIdName": "segah",
                                "noteNameDisplayName": "segāh"
                              }
                            }
                          ]
                        }
                      ],
                      "parameters": {
                        "tuningSystem": {
                          "id": "cairocongresstuningcommittee_1929",
                          "idName": "cairocongresstuningcommittee-1929",
                          "displayName": "Cairo Congress Tuning Committee (1929)"
                        },
                        "startingNote": {
                          "idName": "yegah",
                          "displayName": "yegāh"
                        },
                        "centsTolerance": 5
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Set or maqām not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "setNotFound": {
                    "summary": "Set not found",
                    "value": {
                      "error": "Set 'maqam_invalid_set' not found",
                      "hint": "Use ?setId=<set-id> to filter by a specific set (e.g., ?setId=maqam_rast_set)"
                    }
                  },
                  "maqamNotFound": {
                    "summary": "Maqām not found in any set",
                    "value": {
                      "error": "No sets found containing maqam 'maqam_invalid'",
                      "hint": "Use ?maqamId=<maqam-id> to find sets containing a specific maqām (e.g., ?maqamId=maqam_rast)"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tuning-systems/{id}/{startingNote}/maqamat": {
      "get": {
        "tags": [
          "Tuning Systems"
        ],
        "summary": "List maqāmāt available in a tuning system",
        "description": "Return all maqāmāt that can be realized in a given tuning system beginning on a specific starting note name.\n\n- Feasibility is determined by comparing maqām pitch classes to the tuning system's note name sets (including adjacent octave context)\n",
        "operationId": "listTuningSystemMaqamat",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899')",
            "schema": {
              "type": "string"
            },
            "example": "alfarabi_950g"
          },
          {
            "name": "startingNote",
            "in": "path",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh",
            "schema": {
              "type": "string"
            },
            "example": "ushayran"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeMaqamDegrees",
            "in": "query",
            "required": false,
            "description": "When true, each maqām in data includes a `maqamDegrees` object with ascending and descending arrays\nof PAO note name idNames (URL-safe identifiers for scale degrees).\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeDegreeDetails",
            "in": "query",
            "required": false,
            "description": "When true (and when includeMaqamDegrees=true), the endpoint returns `maqamDegrees.ascending` /\n`maqamDegrees.descending` as arrays of objects `{ noteName, englishName, solfege }` instead of\nnote-name strings. The same transformation applies to `transpositions[].maqamDegrees`.\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeTranspositions",
            "in": "query",
            "required": false,
            "description": "When true, each maqām in data includes a `transpositions` array with the other transpositions\n(excluding the base tonic). Each transposition has `tonic` and `maqamDegrees` with ascending/descending\nnote name idNames for that transposed position.\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Maqāmāt list retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "totalNumberOfMaqamat",
                    "tuningSystem",
                    "data"
                  ],
                  "properties": {
                    "totalNumberOfMaqamat": {
                      "type": "integer",
                      "description": "Total number of maqāmāt available in this tuning system with the specified starting note"
                    },
                    "tuningSystem": {
                      "type": "object"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "type": "object"
                    },
                    "links": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid path parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/modulation-routes": {
      "get": {
        "tags": [
          "Modulations"
        ],
        "summary": "Find modulation routes between maqāmāt",
        "description": "Calculate possible modulation routes between maqāmāt, similar to a navigation/maps application.\n\nUses al-Shawwā's 1946 modulation rules to find shortest paths between a source and target maqām,\nwith optional waypoints and return-to-start functionality.\n\n**Key Features:**\n- Finds shortest paths (fewest modulation steps) using BFS algorithm\n- Supports waypoints for multi-stop journeys\n- Optional return-to-start for round-trip routes (reflecting traditional maqām performance practice)\n- Results cached per tuning system + starting note combination for performance\n\n**Graph Structure:**\n- Nodes: Each (maqamId, tonic) pair is a unique node\n- Edges: Modulation possibilities based on al-Shawwā's rules (scale degrees I, III, IV, V, VI)\n\n**Performance Notes:**\n- maxHops is required to prevent combinatorial explosion\n- First request for a tuning system + starting note builds the graph (may take longer)\n- Subsequent requests use cached graph data\n",
        "operationId": "findModulationRoutes",
        "parameters": [
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system identifier (e.g., 'alfarabi_950g', 'ibnsina_1037')",
            "schema": {
              "type": "string"
            },
            "example": "alfarabi_950g"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive).\nThis is MANDATORY as it affects which maqāmāt are available and their modulation possibilities.\n",
            "schema": {
              "type": "string"
            },
            "example": "ushayran"
          },
          {
            "name": "fromMaqam",
            "in": "query",
            "required": true,
            "description": "Source maqam base ID (the starting point of the journey).\nUse the base maqam identifier (e.g., \"maqam_nahawand\"), not the transposition display name.\nCombine with `fromTonic` to specify a particular transposition.\n",
            "schema": {
              "type": "string"
            },
            "example": "maqam_rast"
          },
          {
            "name": "fromTonic",
            "in": "query",
            "required": false,
            "description": "Optional specific tonic for the source maqam (URL-safe).\nIf not specified, uses the canonical (taḥlīl) form.\n",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "toMaqam",
            "in": "query",
            "required": true,
            "description": "Target maqam base ID (the destination of the journey).\nUse the base maqam identifier (e.g., \"maqam_nahawand\"), not the transposition display name.\nCombine with `toTonic` to specify a particular transposition.\n",
            "schema": {
              "type": "string"
            },
            "example": "maqam_hijaz"
          },
          {
            "name": "toTonic",
            "in": "query",
            "required": false,
            "description": "Optional specific tonic for the target maqam (URL-safe).\nIf not specified, uses the canonical (taḥlīl) form.\n",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "maxHops",
            "in": "query",
            "required": true,
            "description": "Maximum number of modulation steps allowed (required safeguard).\nPrevents combinatorial explosion in route calculation.\nMost musical modulation sequences are 2-4 hops.\nMaximum allowed value is 10.\n",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            },
            "example": 5
          },
          {
            "name": "waypoints",
            "in": "query",
            "required": false,
            "description": "Optional comma-separated waypoints to pass through.\nFormat: maqamId:tonicId or just maqamId (uses canonical tonic).\nExample: \"maqam_bayyat:dugah,maqam_saba\"\n",
            "schema": {
              "type": "string"
            },
            "example": "maqam_bayyat:dugah"
          },
          {
            "name": "returnToStart",
            "in": "query",
            "required": false,
            "description": "Whether to calculate the return path back to the source maqam.\nReflects traditional maqām performance practice where music returns to the starting mode.\nWhen true, response includes both outbound and return routes.\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of routes to return",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 10
            },
            "example": 10
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\nAdds Arabic versions with \"Ar\" suffix (e.g., maqamDisplayNameAr, tonicDisplayAr)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Modulation routes calculated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "routes",
                    "context"
                  ],
                  "properties": {
                    "routes": {
                      "type": "object",
                      "required": [
                        "count",
                        "data"
                      ],
                      "properties": {
                        "count": {
                          "type": "integer",
                          "description": "Number of routes found"
                        },
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ModulationJourney"
                          }
                        }
                      }
                    },
                    "context": {
                      "type": "object",
                      "properties": {
                        "tuningSystem": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            },
                            "displayNameAr": {
                              "type": "string"
                            }
                          }
                        },
                        "startingNote": {
                          "type": "object",
                          "properties": {
                            "idName": {
                              "type": "string"
                            },
                            "displayName": {
                              "type": "string"
                            },
                            "displayNameAr": {
                              "type": "string"
                            }
                          }
                        },
                        "sourceNode": {
                          "$ref": "#/components/schemas/MaqamNode"
                        },
                        "targetNode": {
                          "$ref": "#/components/schemas/MaqamNode"
                        },
                        "waypoints": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/MaqamNode"
                          }
                        },
                        "searchConstraints": {
                          "type": "object",
                          "properties": {
                            "maxHops": {
                              "type": "integer"
                            },
                            "returnToStart": {
                              "type": "boolean"
                            },
                            "limit": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "description": "Present when no routes found, explains why"
                    }
                  }
                },
                "examples": {
                  "routeFound": {
                    "summary": "Successful route finding",
                    "value": {
                      "routes": {
                        "count": 1,
                        "data": [
                          {
                            "totalHops": 2,
                            "outboundRoute": {
                              "hops": 2,
                              "path": [
                                {
                                  "from": {
                                    "maqamId": "1",
                                    "baseMaqamIdName": "maqam_rast",
                                    "maqamIdName": "maqam_rast",
                                    "maqamDisplayName": "maqām rāst",
                                    "tonicId": "rast",
                                    "tonicDisplay": "rāst",
                                    "isTransposition": false
                                  },
                                  "to": {
                                    "maqamId": "2",
                                    "baseMaqamIdName": "maqam_bayyat",
                                    "maqamIdName": "maqam_bayyat",
                                    "maqamDisplayName": "maqām bayyāt",
                                    "tonicId": "dugah",
                                    "tonicDisplay": "dūgāh",
                                    "isTransposition": false
                                  },
                                  "modulationDegree": "III",
                                  "modulationCategory": "thirdDegree"
                                },
                                {
                                  "from": {
                                    "maqamId": "2",
                                    "baseMaqamIdName": "maqam_bayyat",
                                    "maqamIdName": "maqam_bayyat",
                                    "maqamDisplayName": "maqām bayyāt",
                                    "tonicId": "dugah",
                                    "tonicDisplay": "dūgāh",
                                    "isTransposition": false
                                  },
                                  "to": {
                                    "maqamId": "5",
                                    "baseMaqamIdName": "maqam_hijaz",
                                    "maqamIdName": "maqam_hijaz",
                                    "maqamDisplayName": "maqām ḥijāz",
                                    "tonicId": "nawa",
                                    "tonicDisplay": "nawā",
                                    "isTransposition": false
                                  },
                                  "modulationDegree": "IV",
                                  "modulationCategory": "fourthDegree"
                                }
                              ]
                            }
                          }
                        ]
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "alfarabi_950g",
                          "displayName": "al-Fārābī (950) غ"
                        },
                        "startingNote": {
                          "idName": "ushayran",
                          "displayName": "ʿushayrān"
                        },
                        "sourceNode": {
                          "maqamId": "maqam_rast",
                          "maqamDisplayName": "Maqam Rast",
                          "tonicId": "rast",
                          "tonicDisplay": "rāst",
                          "isTransposition": false
                        },
                        "targetNode": {
                          "maqamId": "maqam_hijaz",
                          "maqamDisplayName": "Maqam Hijaz",
                          "tonicId": "nawa",
                          "tonicDisplay": "nawā",
                          "isTransposition": false
                        },
                        "searchConstraints": {
                          "maxHops": 5,
                          "returnToStart": false,
                          "limit": 10
                        }
                      }
                    }
                  },
                  "noRouteFound": {
                    "summary": "No path found within constraints",
                    "value": {
                      "routes": {
                        "count": 0,
                        "data": []
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "alfarabi_950g",
                          "displayName": "al-Fārābī (950) غ"
                        },
                        "startingNote": {
                          "idName": "ushayran",
                          "displayName": "ʿushayrān"
                        },
                        "sourceNode": {
                          "maqamId": "maqam_rast",
                          "maqamDisplayName": "Maqam Rast",
                          "tonicId": "rast",
                          "tonicDisplay": "rāst",
                          "isTransposition": false
                        },
                        "targetNode": {
                          "maqamId": "maqam_sikah",
                          "maqamDisplayName": "Maqam Sikah",
                          "tonicId": "segah",
                          "tonicDisplay": "segāh",
                          "isTransposition": false
                        },
                        "searchConstraints": {
                          "maxHops": 3,
                          "returnToStart": false,
                          "limit": 10
                        }
                      },
                      "message": "No path found from 'maqam_rast' to 'maqam_sikah' within 3 hops"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingMaxHops": {
                    "value": {
                      "error": "maxHops parameter is required",
                      "message": "maxHops is required to prevent combinatorial explosion in route calculation.",
                      "hint": "Add &maxHops=5 to your request. Recommended values: 3-7 for most use cases."
                    }
                  },
                  "maxHopsExceeded": {
                    "value": {
                      "error": "maxHops cannot exceed 10",
                      "message": "Higher values may cause performance issues. Most musical modulation sequences are 2-4 hops.",
                      "hint": "Use maxHops=10 or lower"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Maqam or tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/ajnas": {
      "get": {
        "tags": [
          "Ajnās"
        ],
        "summary": "List all ajnās",
        "description": "Return all ajnās (singular: jins) with metadata.\n\n- Includes URL-safe identifiers, display names, and structural information\n- Structural information includes note sequences needed for maqām construction and analysis\n- Optional bibliographic source references (sourceId and page) when `includeSources=true`\n",
        "operationId": "listAjnas",
        "parameters": [
          {
            "name": "filterByTonic",
            "in": "query",
            "description": "Filter by jins tonic/first note (URL-safe, case-insensitive, diacritics-insensitive)",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": [
                "tonic",
                "alphabetical"
              ],
              "default": "alphabetical"
            },
            "examples": {
              "tonic": {
                "value": "tonic",
                "summary": "Sort by tonic note priority (NoteName.ts order)"
              },
              "alphabetical": {
                "value": "alphabetical",
                "summary": "Sort alphabetically by display name"
              }
            }
          },
          {
            "name": "includeSources",
            "in": "query",
            "required": false,
            "description": "Include bibliographic source references (sourceId and page) for each jins",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "List of ajnās retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "data"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Total number of ajnās"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "jins": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "tonic": {
                            "$ref": "#/components/schemas/IdentifierRef"
                          },
                          "stats": {
                            "type": "object",
                            "properties": {
                              "numberOfPitchClasses": {
                                "type": "integer"
                              },
                              "availableInTuningSystems": {
                                "type": "integer"
                              }
                            }
                          },
                          "availability": {
                            "type": "object",
                            "properties": {
                              "tuningSystems": {
                                "type": "array"
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "description": "Bibliographic source references for this jins",
                            "items": {
                              "type": "object",
                              "properties": {
                                "sourceId": {
                                  "type": "string",
                                  "description": "URL-safe source identifier",
                                  "example": "al-Shawwa-(1946)"
                                },
                                "page": {
                                  "type": "string",
                                  "description": "Page number or range where the jins is documented",
                                  "example": "49"
                                }
                              }
                            }
                          },
                          "links": {
                            "$ref": "#/components/schemas/Links"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/ajnas/{idName}": {
      "get": {
        "tags": [
          "Ajnās"
        ],
        "summary": "Get detailed jins data",
        "description": "Retrieve comprehensive data for a specific jins on its conventional or a transposed tonic, in a specific tuning system on a specific starting note name.\n\nReturns:\n- Comprehensive pitch class data in the requested tuning system and starting note name\n- Optional includeIntervals data, transposition to different tonics, and tuning-system-specific modulations (including lower octave)\n\nParameter Discovery:\n- Use options=true to discover valid values for all parameters including dynamically calculated transposition options\n- Especially useful for finding valid tuning system starting notes and transposition tonics for a specific jins\n\nImportant:\n- When options=true, the endpoint returns parameter discovery metadata instead of jins data\n- This mode is mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, pitch class data type, includeIntervals)\n- If data-returning parameters are provided with options=true, the API returns a 400 Bad Request error with details about conflicting parameters\n\nRequirements:\n- Tuning system and starting note are required for all requests (both data retrieval and discovery mode)\n- These are fundamental to all pitch class calculations\n",
        "operationId": "getJins",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe jins identifier",
            "schema": {
              "type": "string"
            },
            "examples": {
              "rast": {
                "value": "jins_rast",
                "summary": "Jins Rāst (representative example - with zalzalian intervals)"
              },
              "kurd": {
                "value": "jins_kurd",
                "summary": "Jins Kurd (representative example - without zalzalian intervals)"
              },
              "bayyat": {
                "value": "jins_bayyat",
                "summary": "Jins Bayyāt (representative example - with zalzalian intervals)"
              }
            }
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899')",
            "schema": {
              "type": "string"
            },
            "examples": {
              "ibnsina": {
                "value": "ibnsina_1037",
                "summary": "Ibn Sīnā (1037) - 7-Fret Oud 17-Tone (representative example)"
              },
              "farabi": {
                "value": "alfarabi_950g",
                "summary": "al-Fārābī (950g) - First Oud Tuning 27-Tone (representative example)"
              },
              "meshshaqa": {
                "value": "meshshaqa_1899",
                "summary": "Meshshāqa (1899) - Arabic Octave According to the Modernists (representative example)"
              }
            }
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive).\n\n- Mandatory for all pitch class calculations\n- Different starting notes represent different theoretical frameworks within the same tuning system\n- Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string"
            },
            "examples": {
              "yegah": {
                "value": "yegah",
                "summary": "yegāh (for IbnSina, Meshshaqa)"
              },
              "ushayran": {
                "value": "ushayran",
                "summary": "ʿushayrān (for al-Farabi, al-Kindi)"
              },
              "rast": {
                "value": "rast",
                "summary": "rāst (for CairoCongress, al-Sabbagh)"
              }
            }
          },
          {
            "name": "options",
            "in": "query",
            "description": "When true, returns available parameter options instead of jins data.\n\n- Useful for discovering valid values for tuning systems, starting notes, and other parameters\n- Tuning system and starting note are required for all requests (both data retrieval and discovery mode)\n- These are fundamental to all pitch class calculations and calculate valid starting note options and transposition tonics\n- Mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, pitch class data type, intervals)\n- Transposition options are dynamically calculated based on the specific jins, tuning system, and starting note combination\n- Only tonics where the jins can be validly transposed (preserving interval pattern) are included, not all possible pitch classes\n- If data-returning parameters are provided, returns 400 Bad Request error with details about conflicting parameters\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": false,
            "description": "Specifies which pitch class data type to return for each pitch class.\n\n- Optional parameter. When omitted, returns only minimal pitch class fields: `pitchClassIndex`, `octave`, `scaleDegree`, `noteName`, `noteNameDisplay`, and `noteNameDisplayAr` (if includeArabic is enabled)\n- When provided, returns the specified data type for all pitch classes in the jins\n- In discovery mode (when options=true), this parameter is optional since the response returns parameter metadata instead of formatted data\n- Use 'all' for complete pitch class data across all available formats\n",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "abjadName",
                "englishName",
                "solfege",
                "fraction",
                "cents",
                "centsDeviation",
                "decimalRatio",
                "stringLength",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "frequency",
                "referenceNoteName"
              ]
            },
            "example": "cents"
          },
          {
            "name": "transposeTo",
            "in": "query",
            "description": "Transpose the jins to a new tonic by preserving the interval patterns (URL-safe, diacritics-insensitive).\n\n- Only tonics where the jins can be validly transposed in the specified tuning system and starting note are valid\n- To see all valid transposition options, request available parameter options instead of jins data\n",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "includeIntervals",
            "in": "query",
            "description": "Include interval data between jins degrees",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Jins data retrieved successfully.\n\n- When options is true, the response structure differs and returns available parameter options instead of jins data\n- In that case, transposition options contain only valid transposition tonics for this specific jins, tuning system, and starting note combination\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JinsDetailResponse"
                },
                "examples": {
                  "basic": {
                    "summary": "Basic jins data",
                    "value": {
                      "jins": {
                        "id": "5",
                        "idName": "jins_kurd",
                        "displayName": "Jins Kurd",
                        "version": "2025-10-18T19:41:17.132Z",
                        "tonicId": "rast",
                        "tonicName": "rāst",
                        "transposition": false,
                        "numberOfTranspositions": 17,
                        "numberOfPitchClasses": 4,
                        "commentsEnglish": null,
                        "commentsArabic": null,
                        "sources": [],
                        "pitchClassDataType": "all",
                        "includeIntervals": false
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                          "version": "2025-10-18T19:41:17.132Z",
                          "originalValueType": "fraction",
                          "numberOfPitchClassesSingleOctave": 17,
                          "numberOfPitchClassesAllOctaves": 68,
                          "startingNoteName": "yegah",
                          "referenceFrequency": 440
                        }
                      },
                      "pitchData": [
                        {
                          "pitchClassIndex": 0,
                          "octave": 1,
                          "scaleDegree": "I",
                          "noteName": "rast",
                          "noteNameDisplay": "rāst",
                          "englishName": "C3",
                          "fraction": "1/1",
                          "cents": 0,
                          "decimalRatio": 1,
                          "stringLength": 1000,
                          "frequency": 440,
                          "fretDivision": "0.000",
                          "midiNoteDecimal": 48,
                          "midiNotePlusCentsDeviation": "48 +0.0",
                          "centsDeviation": 0,
                          "ipnReferenceNoteName": "C"
                        },
                        {
                          "pitchClassIndex": 1,
                          "octave": 1,
                          "scaleDegree": "II",
                          "noteName": "dugah",
                          "noteNameDisplay": "dūgāh",
                          "englishName": "D3",
                          "fraction": "204/182",
                          "cents": 204,
                          "decimalRatio": 1.12,
                          "frequency": 492.8
                        }
                      ]
                    }
                  },
                  "transposed": {
                    "summary": "Transposed jins (taṣwīr)",
                    "value": {
                      "jins": {
                        "id": "5",
                        "idName": "jins_kurd",
                        "displayName": "Jins Kurd al-Nawā",
                        "version": "2025-10-18T19:41:17.132Z",
                        "tonicId": "nawa",
                        "tonicName": "nawā",
                        "transposition": true,
                        "originalTonicId": "rast",
                        "originalTonicName": "rāst",
                        "transposedTonicId": "nawa",
                        "transposedTonicName": "nawā",
                        "numberOfTranspositions": 17,
                        "numberOfPitchClasses": 4,
                        "commentsEnglish": null,
                        "commentsArabic": null,
                        "sources": [],
                        "pitchClassDataType": "all",
                        "includeIntervals": false
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                          "version": "2025-10-18T19:41:17.132Z",
                          "originalValueType": "fraction",
                          "numberOfPitchClassesSingleOctave": 17,
                          "numberOfPitchClassesAllOctaves": 68,
                          "startingNoteName": "yegah",
                          "referenceFrequency": 440
                        }
                      },
                      "pitchData": [
                        {
                          "pitchClassIndex": 3,
                          "octave": 1,
                          "scaleDegree": "I",
                          "noteName": "nawa",
                          "noteNameDisplay": "nawā",
                          "englishName": "F3",
                          "fraction": "498/415",
                          "cents": 498
                        }
                      ]
                    }
                  },
                  "withModulations": {
                    "summary": "With modulation networks",
                    "value": {
                      "jins": {
                        "id": "5",
                        "idName": "jins_kurd",
                        "displayName": "Jins Kurd",
                        "tonicId": "rast",
                        "tonicName": "rāst",
                        "transposition": false,
                        "pitchClassDataType": "cents",
                        "includeIntervals": false
                      },
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                          "startingNoteName": "yegah"
                        }
                      },
                      "pitchData": [
                        {
                          "pitchClassIndex": 0,
                          "octave": 1,
                          "scaleDegree": "I",
                          "noteName": "rast",
                          "noteNameDisplay": "rāst",
                          "cents": 0
                        },
                        {
                          "pitchClassIndex": 1,
                          "octave": 1,
                          "scaleDegree": "II",
                          "noteName": "dugah",
                          "noteNameDisplay": "dūgāh",
                          "cents": 204
                        }
                      ]
                    }
                  },
                  "withOptions": {
                    "summary": "Options response (when options=true)",
                    "value": {
                      "jins": "Jins Kurd",
                      "tuningSystem": "ibnsina_1037",
                      "availableParameters": {
                        "tuningSystem": {
                          "required": true,
                          "description": "ID of tuning system (see /availability for options)"
                        },
                        "startingNote": {
                          "options": [
                            "ushayran",
                            "yegah"
                          ],
                          "default": "ushayran",
                          "description": "Theoretical framework for note naming"
                        },
                        "pitchClassDataType": {
                          "options": [
                            "all",
                            "frequency",
                            "cents",
                            "fraction",
                            "decimalRatio",
                            "stringLength",
                            "abjadName",
                            "fretDivision",
                            "midiNoteNumber",
                            "midiNoteDeviation",
                            "centsDeviation",
                            "referenceNoteName",
                            "englishName"
                          ],
                          "default": "cents",
                          "description": "Output format for pitch data. Use 'all' for complete pitch class information."
                        },
                        "includeIntervals": {
                          "type": "boolean",
                          "default": true,
                          "description": "Include interval data between pitch classes"
                        },
                        "transposeTo": {
                          "options": [
                            "rast",
                            "nawa",
                            "dugah"
                          ],
                          "default": null,
                          "description": "Transpose to specific tonic (taṣwīr) - only valid transpositions shown"
                        }
                      },
                      "notes": {
                        "formatOptions": "The 'pitchClassDataType' parameter controls which pitch class properties are returned. Use 'all' for comprehensive data or specific formats like 'cents', 'fraction', etc. for targeted data."
                      },
                      "examples": [
                        "/api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&includeIntervals=true",
                        "/api/ajnas/jins_kurd?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents&includeIntervals=true"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "conflictingParametersWithOptions": {
                    "summary": "Conflicting parameters with options=true",
                    "value": {
                      "error": "Conflicting parameters with options=true",
                      "message": "The following data-returning parameters cannot be used with options=true (parameter discovery mode): includeIntervals",
                      "hint": "Remove all data-returning parameters to use discovery mode, or remove options=true to retrieve jins data.",
                      "conflictingParameters": [
                        "includeIntervals"
                      ],
                      "contextualParametersAllowed": [
                        "tuningSystem",
                        "startingNote"
                      ]
                    }
                  },
                  "missingTuningSystem": {
                    "summary": "Missing required tuningSystem parameter",
                    "value": {
                      "error": "tuningSystem parameter is required",
                      "hint": "Use /api/ajnas/{idName}/availability to see available tuning systems",
                      "availabilityUrl": "/api/ajnas/{idName}/availability"
                    }
                  },
                  "missingStartingNote": {
                    "summary": "Missing required startingNote parameter",
                    "value": {
                      "error": "startingNote parameter is required",
                      "message": "A tuning system starting note must be specified. This is mandatory for all pitch class calculations.",
                      "validOptions": [
                        "ʿushayrān",
                        "yegāh"
                      ],
                      "hint": "Add &startingNote=ʿushayrān to your request"
                    }
                  },
                  "invalidStartingNote": {
                    "summary": "Invalid startingNote value",
                    "value": {
                      "error": "Invalid startingNote 'invalid_note'",
                      "validOptions": [
                        "ʿushayrān",
                        "yegāh"
                      ],
                      "hint": "Valid starting notes for this tuning system: ʿushayrān, yegāh"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Jins not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Jins 'jins_invalid' not found",
                  "hint": "Use /api/ajnas to see all available ajnās"
                }
              }
            }
          },
          "422": {
            "description": "Jins cannot be realized in the specified tuning system",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Jins 'jins_rast' cannot be realized in tuning system 'alkindi_874' with starting note 'ushayran'",
                  "hint": "Use /api/ajnas/{idName}/availability to see compatible tuning systems"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/ajnas/{idName}/availability": {
      "get": {
        "tags": [
          "Ajnās"
        ],
        "summary": "Check jins availability across tuning systems",
        "description": "Return tuning-system availability for a jins.\n\n- Shows which tuning systems on which starting note names can realize the specified jins\n- If `transpositionNoteName` is provided, filters results to show only tuning systems where the jins can be transposed to that specific note\n- Validity is computed against each tuning system's note name sets and the jins's pitch class intervals\n- Availability checking spans 3 octaves to correctly handle ajnās that may span multiple octaves\n",
        "operationId": "getJinsAvailability",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe jins identifier",
            "schema": {
              "type": "string"
            },
            "example": "jins_rast"
          },
          {
            "name": "transpositionNoteName",
            "in": "query",
            "required": false,
            "description": "Filter results to show only tuning systems where the jins can be transposed to this specific note (URL-safe, diacritics-insensitive)",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Availability information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jins",
                    "availability"
                  ],
                  "properties": {
                    "jins": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Numeric identifier for the jins"
                        },
                        "idName": {
                          "type": "string",
                          "description": "URL-safe identifier for the jins (e.g., \"jins_kurd\")"
                        },
                        "displayName": {
                          "type": "string",
                          "description": "Display name with diacritics (e.g., \"Jins Kurd\")"
                        },
                        "transpositionNoteName": {
                          "type": "string",
                          "description": "The transposition note name filter applied (present only when transpositionNoteName parameter is provided)",
                          "example": "nawa"
                        },
                        "version": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of last modification"
                        }
                      }
                    },
                    "availability": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "description": "Number of tuning systems supporting this jins (or supporting the specified transposition if transpositionNoteName is provided)"
                        },
                        "tuningSystems": {
                          "type": "array",
                          "description": "Array of tuning systems where this jins is available (filtered by transposition if transpositionNoteName is provided)",
                          "items": {
                            "$ref": "#/components/schemas/TuningSystemAvailability"
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "withoutTransposition": {
                    "summary": "Without transposition filter",
                    "value": {
                      "jins": {
                        "id": "5",
                        "idName": "jins_kurd",
                        "displayName": "Jins Kurd",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "availability": {
                        "count": 29,
                        "tuningSystems": [
                          {
                            "tuningSystemId": "ibnsina_1037",
                            "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran",
                              "yegah"
                            ]
                          },
                          {
                            "tuningSystemId": "alfarabi_950g",
                            "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran",
                              "yegah"
                            ]
                          }
                        ]
                      }
                    }
                  },
                  "withTransposition": {
                    "summary": "With transposition filter (transpositionNoteName=nawa)",
                    "value": {
                      "jins": {
                        "id": "5",
                        "idName": "jins_kurd",
                        "displayName": "Jins Kurd",
                        "transpositionNoteName": "nawa",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "availability": {
                        "count": 15,
                        "tuningSystems": [
                          {
                            "tuningSystemId": "ibnsina_1037",
                            "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran"
                            ]
                          },
                          {
                            "tuningSystemId": "alfarabi_950g",
                            "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)",
                            "tuningSystemStartingNoteNames": [
                              "ʿushayrān",
                              "yegāh"
                            ],
                            "tuningSystemStartingNoteNamesIds": [
                              "ushayran",
                              "yegah"
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "emptyTranspositionNoteName": {
                    "summary": "Empty transpositionNoteName parameter",
                    "value": {
                      "error": "Invalid parameter: transpositionNoteName",
                      "message": "The 'transpositionNoteName' parameter cannot be empty.",
                      "hint": "Provide a valid note name like ?transpositionNoteName=nawa or remove the parameter"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Jins not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Jins 'jins_invalid' not found",
                  "hint": "Use /api/ajnas to see all available ajnās"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/ajnas/{idName}/transpositions": {
      "get": {
        "tags": [
          "Ajnās"
        ],
        "summary": "List transpositions for a jins",
        "description": "List all available transposition options for a jins within a specific tuning system and starting note.\n\nReturns all tonic transpositions that are feasible under the tuning system across all octaves.\n",
        "operationId": "listJinsTranspositions",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe jins identifier",
            "schema": {
              "type": "string"
            },
            "example": "jins_bayyat"
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899')",
            "schema": {
              "type": "string"
            },
            "example": "meshshaqa_1899"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh",
            "schema": {
              "type": "string"
            },
            "example": "yegah"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Transpositions retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jins": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Numeric identifier for the jins"
                        },
                        "idName": {
                          "type": "string",
                          "description": "URL-safe identifier for the jins"
                        },
                        "displayName": {
                          "type": "string",
                          "description": "Display name with diacritics (e.g., \"Jins Kurd\")"
                        },
                        "version": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of last modification"
                        }
                      }
                    },
                    "context": {
                      "type": "object",
                      "properties": {
                        "tuningSystem": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Tuning system identifier"
                            },
                            "displayName": {
                              "type": "string",
                              "description": "Display name formatted as \"Creator (Year) Title\" (e.g., \"Ibn Sīnā (1037) 7-Fret Oud 17-Tone\")"
                            },
                            "version": {
                              "type": "string",
                              "description": "ISO 8601 timestamp of last modification"
                            }
                          }
                        },
                        "startingNote": {
                          "type": "string",
                          "description": "Tuning system starting note name with diacritics"
                        },
                        "pitchClassesInOctave": {
                          "type": "integer",
                          "description": "Number of pitch classes in a single octave (not counting adjacent octaves)"
                        }
                      }
                    },
                    "transpositions": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total number of transpositions available"
                        },
                        "list": {
                          "type": "array",
                          "description": "Array of transposition options",
                          "items": {
                            "type": "object",
                            "properties": {
                              "tonicId": {
                                "type": "string",
                                "description": "URL-safe tonic note identifier"
                              },
                              "tonicName": {
                                "type": "string",
                                "description": "Tonic note name with diacritics"
                              },
                              "pitchClassIndex": {
                                "type": "integer",
                                "description": "Index of the tonic pitch class in the tuning system"
                              },
                              "octave": {
                                "type": "integer",
                                "description": "Octave number of the tonic (1 = primary octave, 2 = octave above, etc.)"
                              },
                              "dataHref": {
                                "type": "string",
                                "description": "URL to retrieve full jins data for this transposition"
                              }
                            }
                          }
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string",
                          "description": "Link to this endpoint"
                        },
                        "availability": {
                          "type": "string",
                          "description": "Link to availability endpoint"
                        },
                        "jins": {
                          "type": "string",
                          "description": "Link to jins detail endpoint"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingTuningSystem": {
                    "summary": "Missing tuningSystem parameter",
                    "value": {
                      "error": "tuningSystem parameter is required",
                      "hint": "Add ?tuningSystem=ibnsina_1037 to your request. Use /api/ajnas/{id}/availability to see available tuning systems"
                    }
                  },
                  "missingStartingNote": {
                    "summary": "Missing startingNote parameter",
                    "value": {
                      "error": "startingNote parameter is required",
                      "hint": "Add &startingNote=yegah to your request. Use /api/ajnas/{id}/availability to see available starting notes"
                    }
                  },
                  "invalidStartingNote": {
                    "summary": "Invalid starting note for tuning system",
                    "value": {
                      "error": "Starting note 'invalid' is not valid for tuning system 'ibnsina_1037'",
                      "validOptions": [
                        "ʿushayrān",
                        "yegāh"
                      ]
                    }
                  },
                  "jinsNotPossible": {
                    "summary": "Jins not possible in this context",
                    "value": {
                      "error": "Jins 'Jins Kurd' is not possible in tuning system 'ibnsina_1037' with starting note 'yegāh'",
                      "hint": "Use /api/ajnas/{id}/availability to find compatible combinations"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Jins or tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "jinsNotFound": {
                    "summary": "Jins not found",
                    "value": {
                      "error": "Jins 'jins_invalid' not found",
                      "hint": "Use /api/ajnas to see all available ajnās"
                    }
                  },
                  "tuningSystemNotFound": {
                    "summary": "Tuning system not found",
                    "value": {
                      "error": "Tuning system 'invalid' not found",
                      "hint": "Use /api/tuning-systems to see all available tuning systems"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/ajnas/{idName}/compare": {
      "get": {
        "tags": [
          "Ajnās"
        ],
        "summary": "Compare jins data across multiple tuning systems",
        "description": "Compare comprehensive jins data across multiple tuning systems and starting note configurations in a single request.\n\nReturns comprehensive data similar to `/ajnas/{idName}` but without modulations. Each comparison includes:\n- Pitch class data (single sequence, as ajnās are unidirectional)\n- Optional interval data\n- Jins metadata (tonic, transposition status)\n- Context information (tuning system, starting note, reference frequency)\n\nThis endpoint is ideal for comparative musicological analysis of melodic structures across different historical tuning systems.\n",
        "operationId": "compareJins",
        "parameters": [
          {
            "name": "idName",
            "in": "path",
            "required": true,
            "description": "URL-safe jins identifier",
            "schema": {
              "type": "string"
            },
            "example": "jins_segah"
          },
          {
            "name": "tuningSystems",
            "in": "query",
            "required": true,
            "description": "Comma-separated tuning system IDs. All tuning systems will use the same starting note and optional transposition.\n",
            "schema": {
              "type": "string"
            },
            "example": "alfarabi_950g,meshshaqa_1899"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Starting note name (URL-safe, diacritics-insensitive) - applies to all tuning systems. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh",
            "schema": {
              "type": "string"
            },
            "example": "ushayran"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": true,
            "description": "Output format for pitch class data",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "englishName",
                "fraction",
                "cents",
                "decimalRatio",
                "stringLength",
                "frequency",
                "abjadName",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "centsDeviation",
                "referenceNoteName"
              ]
            },
            "default": "cents",
            "example": "cents"
          },
          {
            "name": "includeIntervals",
            "in": "query",
            "required": false,
            "description": "Include interval data between pitch classes",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          },
          {
            "name": "transposeTo",
            "in": "query",
            "required": false,
            "description": "Transpose to specific tonic note (applies to all tuning systems)",
            "schema": {
              "type": "string"
            },
            "example": "nawa"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jins",
                    "comparisons",
                    "meta"
                  ],
                  "properties": {
                    "jins": {
                      "type": "object",
                      "description": "Original jins identifier information",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Numeric identifier for the jins"
                        },
                        "idName": {
                          "type": "string",
                          "description": "URL-safe identifier for the jins"
                        },
                        "displayName": {
                          "type": "string",
                          "description": "Display name with diacritics"
                        },
                        "version": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of last modification"
                        }
                      }
                    },
                    "comparisons": {
                      "type": "array",
                      "description": "Array of comparison results (one per configuration)",
                      "items": {
                        "type": "object",
                        "properties": {
                          "jins": {
                            "type": "object",
                            "description": "Jins data for this comparison (may include transposition info)",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "idName": {
                                "type": "string"
                              },
                              "displayName": {
                                "type": "string"
                              },
                              "version": {
                                "type": "string"
                              },
                              "tonicId": {
                                "type": "string",
                                "description": "URL-safe tonic note identifier"
                              },
                              "tonicName": {
                                "type": "string",
                                "description": "Tonic note name with diacritics"
                              },
                              "transposition": {
                                "type": "boolean",
                                "description": "Whether this is a transposition from the original tonic"
                              },
                              "originalTonicId": {
                                "type": "string",
                                "description": "Original tonic identifier (present only if transposed)"
                              },
                              "originalTonicName": {
                                "type": "string",
                                "description": "Original tonic name (present only if transposed)"
                              },
                              "numberOfPitchClasses": {
                                "type": "integer",
                                "description": "Number of pitch classes in this jins"
                              },
                              "pitchClassDataType": {
                                "type": "string",
                                "description": "Format used for pitch class data"
                              },
                              "includeIntervals": {
                                "type": "boolean",
                                "description": "Whether intervals are included"
                              }
                            }
                          },
                          "context": {
                            "type": "object",
                            "properties": {
                              "tuningSystem": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "description": "Tuning system identifier"
                                  }
                                }
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Display name formatted as \"Creator (Year) Title\""
                              },
                              "version": {
                                "type": "string",
                                "description": "ISO 8601 timestamp of last modification"
                              },
                              "numberOfPitchClassesSingleOctave": {
                                "type": "integer",
                                "description": "Number of pitch classes in one octave of the selected tuning system (from tuning system's original pitch class values)"
                              },
                              "startingNoteName": {
                                "type": "string",
                                "description": "Starting note name (URL-safe)"
                              },
                              "referenceFrequency": {
                                "type": "number",
                                "description": "Reference frequency in Hz associated with the starting note name (falls back to tuning system default if not specified for this note)"
                              }
                            }
                          },
                          "pitchData": {
                            "type": "array",
                            "description": "Pitch class sequence (ajnās are unidirectional)",
                            "items": {
                              "type": "object"
                            }
                          },
                          "intervals": {
                            "type": "array",
                            "description": "Interval data (present only if includeIntervals=true)",
                            "items": {
                              "type": "object"
                            }
                          },
                          "error": {
                            "type": "string",
                            "description": "Error message if this comparison failed"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "totalComparisons": {
                          "type": "integer",
                          "description": "Total number of comparisons requested"
                        },
                        "successfulComparisons": {
                          "type": "integer",
                          "description": "Number of successful comparisons"
                        },
                        "failedComparisons": {
                          "type": "integer",
                          "description": "Number of failed comparisons"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "twoTuningSystems": {
                    "summary": "Compare across two tuning systems",
                    "value": {
                      "jins": {
                        "id": "5",
                        "idName": "jins_kurd",
                        "displayName": "Jins Kurd",
                        "version": "2025-10-18T19:41:17.132Z"
                      },
                      "comparisons": [
                        {
                          "jins": {
                            "id": "5",
                            "idName": "jins_kurd",
                            "displayName": "Jins Kurd",
                            "version": "2025-10-18T19:41:17.132Z",
                            "tonicId": "rast",
                            "tonicName": "rāst",
                            "transposition": false,
                            "numberOfPitchClasses": 4,
                            "pitchClassDataType": "cents",
                            "includeIntervals": true
                          },
                          "context": {
                            "tuningSystem": {
                              "id": "ibnsina_1037",
                              "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                              "version": "2025-10-18T19:41:17.132Z",
                              "numberOfPitchClassesSingleOctave": 17,
                              "startingNoteName": "yegah",
                              "referenceFrequency": 440
                            }
                          },
                          "pitchData": [
                            {
                              "pitchClassIndex": 0,
                              "octave": 1,
                              "scaleDegree": "I",
                              "noteName": "rast",
                              "noteNameDisplay": "rāst",
                              "cents": 0
                            },
                            {
                              "pitchClassIndex": 1,
                              "octave": 1,
                              "scaleDegree": "II",
                              "noteName": "dugah",
                              "noteNameDisplay": "dūgāh",
                              "cents": 204
                            },
                            {
                              "pitchClassIndex": 2,
                              "octave": 1,
                              "scaleDegree": "III",
                              "noteName": "kurd",
                              "noteNameDisplay": "kurd",
                              "cents": 294
                            },
                            {
                              "pitchClassIndex": 3,
                              "octave": 1,
                              "scaleDegree": "IV",
                              "noteName": "nawa",
                              "noteNameDisplay": "nawā",
                              "cents": 498
                            }
                          ],
                          "intervals": [
                            {
                              "cents": 204
                            },
                            {
                              "cents": 90
                            },
                            {
                              "cents": 204
                            }
                          ]
                        },
                        {
                          "jins": {
                            "id": "5",
                            "idName": "jins_kurd",
                            "displayName": "Jins Kurd",
                            "version": "2025-10-18T19:41:17.132Z",
                            "tonicId": "rast",
                            "tonicName": "rāst",
                            "transposition": false,
                            "numberOfPitchClasses": 4,
                            "pitchClassDataType": "cents",
                            "includeIntervals": true
                          },
                          "context": {
                            "tuningSystem": {
                              "id": "ibnsina_1037",
                              "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone",
                              "version": "2025-10-18T19:41:17.132Z",
                              "numberOfPitchClassesSingleOctave": 17,
                              "startingNoteName": "yegah",
                              "referenceFrequency": 440
                            }
                          },
                          "pitchData": [
                            {
                              "pitchClassIndex": 0,
                              "octave": 1,
                              "scaleDegree": "I",
                              "noteName": "rast",
                              "noteNameDisplay": "rāst",
                              "cents": 0
                            },
                            {
                              "pitchClassIndex": 1,
                              "octave": 1,
                              "scaleDegree": "II",
                              "noteName": "dugah",
                              "noteNameDisplay": "dūgāh",
                              "cents": 211.7
                            },
                            {
                              "pitchClassIndex": 2,
                              "octave": 1,
                              "scaleDegree": "III",
                              "noteName": "kurd",
                              "noteNameDisplay": "kurd",
                              "cents": 294.1
                            },
                            {
                              "pitchClassIndex": 3,
                              "octave": 1,
                              "scaleDegree": "IV",
                              "noteName": "nawa",
                              "noteNameDisplay": "nawā",
                              "cents": 498
                            }
                          ],
                          "intervals": [
                            {
                              "cents": 211.7
                            },
                            {
                              "cents": 82.4
                            },
                            {
                              "cents": 203.9
                            }
                          ]
                        }
                      ],
                      "meta": {
                        "totalComparisons": 2,
                        "successfulComparisons": 2,
                        "failedComparisons": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingTuningSystems": {
                    "summary": "Missing tuningSystems parameter",
                    "value": {
                      "error": "tuningSystems parameter is required",
                      "message": "Provide comma-separated tuning system IDs",
                      "hint": "Format: ?tuningSystems=ibnsina_1037,alfarabi_950g",
                      "example": "/api/ajnas/jins_segah/compare?tuningSystems=alfarabi_950g,meshshaqa_1899&startingNote=ushayran&pitchClassDataType=cents"
                    }
                  },
                  "missingStartingNote": {
                    "summary": "Missing startingNote parameter",
                    "value": {
                      "error": "startingNote parameter is required",
                      "message": "A starting note must be specified for all tuning systems",
                      "hint": "Add &startingNote=yegah to your request"
                    }
                  },
                  "invalidIntervals": {
                    "summary": "Invalid includeIntervals parameter",
                    "value": {
                      "error": "Invalid parameter: includeIntervals",
                      "message": "The 'includeIntervals' parameter must be 'true' or 'false'.",
                      "validOptions": [
                        "true",
                        "false"
                      ],
                      "hint": "Use ?includeIntervals=true or ?includeIntervals=false"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Jins not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Jins 'jins_invalid' not found",
                  "hint": "Use /api/ajnas to see all available ajnās"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/pitch-classes/note-names": {
      "get": {
        "tags": [
          "Pitch Classes"
        ],
        "summary": "List all note names",
        "description": "Returns all note names used in the app, bilingually, sortable by note name order or alphabetically.\n\nNote names are sourced from all octave arrays in NoteName.ts (octaveZeroNoteNames, octaveOneNoteNames, \noctaveTwoNoteNames, octaveThreeNoteNames, octaveFourNoteNames). Each note name includes:\n- Canonical order (index within its octave array)\n- Octave number (0-4)\n- English IPN equivalent\n\nNote names are unique per octave, so the same note name string in different octaves represents \ndifferent pitch classes.\n\n**Note**: Availability data is not included in this endpoint (it's expensive to calculate). \nUse the availability endpoint (`/api/pitch-classes/note-names/{noteName}/availability`) to get \navailability information for a specific note name.\n",
        "operationId": "listNoteNames",
        "parameters": [
          {
            "name": "sortBy",
            "in": "query",
            "required": false,
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": [
                "order",
                "alphabetical"
              ],
              "default": "order"
            },
            "examples": {
              "order": {
                "value": "order",
                "summary": "Sort by canonical note name order (from NoteName.ts arrays)"
              },
              "alphabetical": {
                "value": "alphabetical",
                "summary": "Sort alphabetically by display name"
              }
            }
          },
          {
            "name": "filterByTuningSystem",
            "in": "query",
            "required": false,
            "description": "Filter by tuning system ID to show only note names that exist in that system (URL-safe, case-insensitive, diacritics-insensitive)",
            "schema": {
              "type": "string"
            },
            "example": "meshshaqa_1899"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "List of note names retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        }
                      }
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "noteName": {
                            "$ref": "#/components/schemas/IdentifierRef"
                          },
                          "englishName": {
                            "type": "string",
                            "description": "International Pitch Notation equivalent",
                            "example": "G3"
                          },
                          "order": {
                            "type": "integer",
                            "description": "Canonical order (index within octave array)",
                            "example": 16
                          },
                          "octave": {
                            "type": "integer",
                            "description": "Octave number (0-4)",
                            "example": 1
                          },
                          "links": {
                            "$ref": "#/components/schemas/Links",
                            "description": "Links to detail and availability endpoints (availability data is only in the availability endpoint)"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Tuning system not found (when filterByTuningSystem is used)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/pitch-classes/note-names/{noteName}": {
      "get": {
        "tags": [
          "Pitch Classes"
        ],
        "summary": "Get pitch class details by note name",
        "description": "Get pitch class details for a note name, across all tuning systems or a specific one.\n\nWhen querying by note name, the note name itself identifies the octave (note names are unique per octave).\nThe octave parameter is optional and can be used for validation.\n\nSupports:\n- Single tuning system with specific starting note\n- Single tuning system with startingNote=\"all\" (returns array for all starting notes)\n- All tuning systems (returns array for all tuning systems and starting notes)\n",
        "operationId": "getPitchClassByNoteName",
        "parameters": [
          {
            "name": "noteName",
            "in": "path",
            "required": true,
            "description": "URL-safe note name (e.g., \"rast\", \"dugah\", \"nawa\")",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": false,
            "description": "Tuning system ID. If provided, returns data for that tuning system only. If omitted, returns data for all tuning systems.",
            "schema": {
              "type": "string"
            },
            "example": "cairocongresstuningcommittee_1929"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": false,
            "description": "Starting note for the tuning system. Required if tuningSystem is provided.\n\n- Use a specific starting note name (URL-safe) for single result\n- Use \"all\" to include all available starting notes for that tuning system (returns array of results, one per starting note)\n\nNote: Since note names are unique per octave, the note name itself identifies the octave. No octave parameter is needed. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": false,
            "description": "Pitch class data format (defaults to `all` when omitted, matching the handler)",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "abjadName",
                "englishName",
                "solfege",
                "fraction",
                "cents",
                "centsDeviation",
                "decimalRatio",
                "stringLength",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "frequency",
                "referenceNoteName"
              ],
              "default": "all"
            },
            "example": "cents"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Pitch class data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "Single tuning system response",
                      "properties": {
                        "context": {
                          "type": "object",
                          "properties": {
                            "tuningSystem": {
                              "$ref": "#/components/schemas/EntityRef"
                            },
                            "startingNote": {
                              "$ref": "#/components/schemas/IdentifierRef"
                            },
                            "noteName": {
                              "$ref": "#/components/schemas/IdentifierRef"
                            },
                            "referenceFrequency": {
                              "type": "number"
                            },
                            "pitchClassDataType": {
                              "type": "string"
                            }
                          }
                        },
                        "pitchClass": {
                          "$ref": "#/components/schemas/PitchClass"
                        },
                        "links": {
                          "$ref": "#/components/schemas/Links"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "description": "Multiple tuning systems or starting notes response",
                      "properties": {
                        "context": {
                          "type": "object",
                          "properties": {
                            "noteName": {
                              "$ref": "#/components/schemas/IdentifierRef"
                            }
                          }
                        },
                        "pitchClasses": {
                          "type": "array",
                          "description": "Array of pitch class data, one per tuning system/starting note combination",
                          "items": {
                            "type": "object",
                            "properties": {
                              "context": {
                                "type": "object",
                                "properties": {
                                  "tuningSystem": {
                                    "$ref": "#/components/schemas/EntityRef"
                                  },
                                  "startingNote": {
                                    "$ref": "#/components/schemas/IdentifierRef"
                                  },
                                  "referenceFrequency": {
                                    "type": "number"
                                  },
                                  "pitchClassDataType": {
                                    "type": "string"
                                  }
                                }
                              },
                              "pitchClassData": {
                                "$ref": "#/components/schemas/PitchClass"
                              }
                            }
                          }
                        },
                        "links": {
                          "$ref": "#/components/schemas/Links"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Note name or tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/pitch-classes/note-names/{noteName}/availability": {
      "get": {
        "tags": [
          "Pitch Classes"
        ],
        "summary": "Check note name availability across tuning systems",
        "description": "Check which tuning systems support a specific note name and what pitch class index it has in each tuning system.\n\nReturns for each tuning system:\n- All starting notes where the note name exists\n- The pitch class index for each starting note\n- The octave where the note name was found\n",
        "operationId": "getNoteNameAvailability",
        "parameters": [
          {
            "name": "noteName",
            "in": "path",
            "required": true,
            "description": "URL-safe note name (e.g., \"rast\", \"dugah\", \"nawa\")",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Availability data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "noteName": {
                      "$ref": "#/components/schemas/IdentifierRef"
                    },
                    "availability": {
                      "type": "object",
                      "properties": {
                        "meta": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            }
                          }
                        },
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "tuningSystem": {
                                "$ref": "#/components/schemas/EntityRef"
                              },
                              "startingNotes": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "startingNote": {
                                      "$ref": "#/components/schemas/IdentifierRef"
                                    },
                                    "pitchClassIndex": {
                                      "type": "integer",
                                      "description": "Pitch class index within this tuning system"
                                    },
                                    "octave": {
                                      "type": "integer",
                                      "description": "Octave where the note name was found"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Note name not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/pitch-classes/note-names/{noteName}/compare": {
      "get": {
        "tags": [
          "Pitch Classes"
        ],
        "summary": "Compare pitch class by note name across tuning systems",
        "description": "Compare a pitch class (by note name) across different tuning systems.\n\nReturns comprehensive data for each tuning system including:\n- Pitch class data in the requested format\n- Context information (tuning system, starting note, reference frequency)\n",
        "operationId": "comparePitchClassByNoteName",
        "parameters": [
          {
            "name": "noteName",
            "in": "path",
            "required": true,
            "description": "URL-safe note name (e.g., \"rast\", \"dugah\", \"nawa\")",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "tuningSystems",
            "in": "query",
            "required": true,
            "description": "Comma-separated tuning system IDs",
            "schema": {
              "type": "string"
            },
            "example": "meshshaqa_1899,cairocongresstuningcommittee_1929"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Starting note (applies to all tuning systems), or \"all\" to include all available starting notes for each tuning system. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string"
            },
            "example": "yegah"
          },
          {
            "name": "pitchClassDataType",
            "in": "query",
            "required": false,
            "description": "Pitch class data format (defaults to `all` when omitted, matching the handler)",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "abjadName",
                "englishName",
                "solfege",
                "fraction",
                "cents",
                "centsDeviation",
                "decimalRatio",
                "stringLength",
                "fretDivision",
                "midiNoteNumber",
                "midiNoteDeviation",
                "frequency",
                "referenceNoteName"
              ],
              "default": "all"
            },
            "example": "cents"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "noteName": {
                          "$ref": "#/components/schemas/IdentifierRef"
                        }
                      }
                    },
                    "comparisons": {
                      "type": "array",
                      "description": "Array of comparison results, one per tuning system/starting note combination",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tuningSystem": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "startingNote": {
                            "$ref": "#/components/schemas/IdentifierRef"
                          },
                          "pitchClass": {
                            "$ref": "#/components/schemas/PitchClass"
                          },
                          "context": {
                            "type": "object",
                            "properties": {
                              "referenceFrequency": {
                                "type": "number"
                              },
                              "pitchClassDataType": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "totalComparisons": {
                          "type": "integer"
                        },
                        "successfulComparisons": {
                          "type": "integer"
                        },
                        "failedComparisons": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Note name not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/intervals": {
      "get": {
        "tags": [
          "Intervals"
        ],
        "summary": "Calculate intervals by note names",
        "description": "Get interval calculations for 2 or more pitch classes by listing their note names.\n\nCalculates intervals between consecutive note names: [0→1, 1→2, 2→3, ...]\n\nSupports:\n- Single tuning system with specific starting note\n- Single tuning system with startingNote=\"all\" (returns array for all starting notes)\n- All tuning systems (returns array for all tuning systems and starting notes)\n\nNote: When querying by note names, the pitchClassIndex field is excluded from interval responses \nas it is not meaningful in this context.\n",
        "operationId": "calculateIntervalsByNoteNames",
        "parameters": [
          {
            "name": "noteNames",
            "in": "query",
            "required": true,
            "description": "Comma-separated note names (e.g., \"rast,dugah,segah\"). Note names can come from any octave.",
            "schema": {
              "type": "string"
            },
            "example": "rast,dugah,segah"
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": false,
            "description": "Tuning system ID. If provided, calculates in that tuning system only. If omitted, calculates in all tuning systems.",
            "schema": {
              "type": "string"
            },
            "example": "alsabbagh_1954"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": false,
            "description": "Starting note. Required if tuningSystem is provided.\n\n- Use a specific starting note name (URL-safe) for single result\n- Use \"all\" to include all available starting notes for that tuning system (returns array of results, one per starting note)\n\nNote: Since note names are unique per octave, each note name already identifies its octave. No octave parameter is needed. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Interval calculations retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "Single tuning system response",
                      "properties": {
                        "context": {
                          "type": "object",
                          "properties": {
                            "noteNames": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/IdentifierRef"
                              }
                            },
                            "tuningSystem": {
                              "$ref": "#/components/schemas/EntityRef"
                            },
                            "startingNote": {
                              "$ref": "#/components/schemas/IdentifierRef"
                            },
                            "referenceFrequency": {
                              "type": "number"
                            }
                          }
                        },
                        "intervals": {
                          "type": "array",
                          "description": "Array of intervals between consecutive note names [0→1, 1→2, 2→3, ...]",
                          "items": {
                            "type": "object",
                            "properties": {
                              "from": {
                                "$ref": "#/components/schemas/IdentifierRef"
                              },
                              "to": {
                                "$ref": "#/components/schemas/IdentifierRef"
                              },
                              "interval": {
                                "type": "object",
                                "description": "Interval data (excludes pitchClassIndex when querying by note names)",
                                "properties": {
                                  "fraction": {
                                    "type": "string"
                                  },
                                  "cents": {
                                    "type": "number"
                                  },
                                  "decimalRatio": {
                                    "type": "number"
                                  },
                                  "stringLength": {
                                    "type": "number"
                                  },
                                  "fretDivision": {
                                    "type": "number"
                                  },
                                  "originalValue": {
                                    "type": "string"
                                  },
                                  "originalValueType": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "links": {
                          "$ref": "#/components/schemas/Links"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "description": "Multiple tuning systems or starting notes response",
                      "properties": {
                        "context": {
                          "type": "object",
                          "properties": {
                            "noteNames": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/IdentifierRef"
                              }
                            }
                          }
                        },
                        "intervals": {
                          "type": "array",
                          "description": "Array of interval calculations, one per tuning system/starting note combination",
                          "items": {
                            "type": "object",
                            "properties": {
                              "intervals": {
                                "type": "array",
                                "description": "Array of intervals between consecutive note names [0→1, 1→2, 2→3, ...]",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "from": {
                                      "$ref": "#/components/schemas/IdentifierRef"
                                    },
                                    "to": {
                                      "$ref": "#/components/schemas/IdentifierRef"
                                    },
                                    "interval": {
                                      "type": "object"
                                    }
                                  }
                                }
                              },
                              "context": {
                                "type": "object",
                                "properties": {
                                  "tuningSystem": {
                                    "$ref": "#/components/schemas/EntityRef"
                                  },
                                  "startingNote": {
                                    "$ref": "#/components/schemas/IdentifierRef"
                                  },
                                  "referenceFrequency": {
                                    "type": "number"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "links": {
                          "$ref": "#/components/schemas/Links"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Note name or tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/intervals/compare": {
      "get": {
        "tags": [
          "Intervals"
        ],
        "summary": "Compare intervals across tuning systems",
        "description": "Compare interval calculations for 2+ pitch classes across different tuning systems by listing their note names.\n\nCalculates intervals between consecutive note names: [0→1, 1→2, 2→3, ...]\n\nNote: When querying by note names, the pitchClassIndex field is excluded from interval responses \nas it is not meaningful in this context.\n",
        "operationId": "compareIntervalsByNoteNames",
        "parameters": [
          {
            "name": "noteNames",
            "in": "query",
            "required": true,
            "description": "Comma-separated note names. Note names can come from any octave.",
            "schema": {
              "type": "string"
            },
            "example": "rast,dugah,segah"
          },
          {
            "name": "tuningSystems",
            "in": "query",
            "required": true,
            "description": "Comma-separated tuning system IDs",
            "schema": {
              "type": "string"
            },
            "example": "alfarabi_950g,cairocongresstuningcommittee_1929"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Starting note (applies to all tuning systems), or \"all\" to include all available starting notes for each tuning system.\n\nWhen \"all\" is used, the endpoint returns results for all valid starting notes in each tuning system, allowing comprehensive comparison across all theoretical frameworks.\n\nNote: Since note names are unique per octave, each note name already identifies its octave. No octave parameter is needed. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh\n",
            "schema": {
              "type": "string"
            },
            "example": "ushayran"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "noteNames": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/IdentifierRef"
                          }
                        }
                      }
                    },
                    "comparisons": {
                      "type": "array",
                      "description": "Array of comparison results, one per tuning system/starting note combination",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tuningSystem": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "startingNote": {
                            "$ref": "#/components/schemas/IdentifierRef"
                          },
                          "intervals": {
                            "type": "array",
                            "description": "Array of intervals between consecutive note names [0→1, 1→2, 2→3, ...]",
                            "items": {
                              "type": "object",
                              "properties": {
                                "from": {
                                  "$ref": "#/components/schemas/IdentifierRef"
                                },
                                "to": {
                                  "$ref": "#/components/schemas/IdentifierRef"
                                },
                                "interval": {
                                  "type": "object",
                                  "description": "Interval data (excludes pitchClassIndex when querying by note names)",
                                  "properties": {
                                    "fraction": {
                                      "type": "string"
                                    },
                                    "cents": {
                                      "type": "number"
                                    },
                                    "decimalRatio": {
                                      "type": "number"
                                    },
                                    "stringLength": {
                                      "type": "number"
                                    },
                                    "fretDivision": {
                                      "type": "number"
                                    },
                                    "originalValue": {
                                      "type": "string"
                                    },
                                    "originalValueType": {
                                      "type": "string"
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "context": {
                            "type": "object",
                            "properties": {
                              "referenceFrequency": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "totalComparisons": {
                          "type": "integer"
                        },
                        "successfulComparisons": {
                          "type": "integer"
                        },
                        "failedComparisons": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Note name not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/intervals/calculate": {
      "get": {
        "tags": [
          "Intervals"
        ],
        "summary": "Calculate interval between two pitch classes",
        "description": "Calculate the interval between two pitch classes in a specific tuning system.\n\nSupports flexible pitch class identification:\n- By note name (e.g., \"rast\", \"dugah\")\n- By value in any format: fraction (e.g., \"3/2\"), cents (e.g., \"701.955\"), decimalRatio (e.g., \"1.5\"), stringLength, or fretDivision\n\nReturns the interval in the requested unit format, plus all other unit formats for reference.\n",
        "operationId": "calculateIntervalBetweenPitchClasses",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "First pitch class identifier (note name or value)",
            "schema": {
              "type": "string"
            },
            "example": "rast"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Second pitch class identifier (note name or value)",
            "schema": {
              "type": "string"
            },
            "example": "dugah"
          },
          {
            "name": "tuningSystem",
            "in": "query",
            "required": true,
            "description": "Tuning system ID",
            "schema": {
              "type": "string"
            },
            "example": "ibnsina_1037"
          },
          {
            "name": "startingNote",
            "in": "query",
            "required": true,
            "description": "Starting note for the tuning system",
            "schema": {
              "type": "string"
            },
            "example": "yegah"
          },
          {
            "name": "unit",
            "in": "query",
            "required": true,
            "description": "Output unit format for the interval",
            "schema": {
              "type": "string",
              "enum": [
                "fraction",
                "cents",
                "centsFromZero",
                "decimalRatio",
                "stringLength",
                "fretDivision"
              ]
            },
            "example": "cents"
          },
          {
            "name": "fromType",
            "in": "query",
            "required": false,
            "description": "Type of 'from' value if it's a value (not a note name).\nRequired if 'from' is a value and cannot be auto-detected.\n",
            "schema": {
              "type": "string",
              "enum": [
                "fraction",
                "cents",
                "decimalRatio",
                "stringLength",
                "fretDivision"
              ]
            },
            "example": "fraction"
          },
          {
            "name": "toType",
            "in": "query",
            "required": false,
            "description": "Type of 'to' value if it's a value (not a note name).\nRequired if 'to' is a value and cannot be auto-detected.\n",
            "schema": {
              "type": "string",
              "enum": [
                "fraction",
                "cents",
                "decimalRatio",
                "stringLength",
                "fretDivision"
              ]
            },
            "example": "fraction"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Interval calculated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "tuningSystem": {
                          "$ref": "#/components/schemas/EntityRef"
                        },
                        "startingNote": {
                          "$ref": "#/components/schemas/IdentifierRef"
                        },
                        "referenceFrequency": {
                          "type": "number",
                          "description": "Reference frequency in Hz"
                        }
                      }
                    },
                    "from": {
                      "type": "object",
                      "properties": {
                        "pitchClass": {
                          "type": "object",
                          "properties": {
                            "pitchClassIndex": {
                              "type": "integer"
                            },
                            "octave": {
                              "type": "integer"
                            },
                            "noteName": {
                              "type": "string",
                              "description": "URL-safe note name"
                            },
                            "noteNameDisplay": {
                              "type": "string",
                              "description": "Display note name with diacritics"
                            },
                            "noteNameDisplayAr": {
                              "type": "string",
                              "description": "Arabic note name (if includeArabic=true)"
                            },
                            "englishName": {
                              "type": "string"
                            },
                            "solfege": {
                              "type": "string"
                            },
                            "abjadName": {
                              "type": "string"
                            },
                            "fraction": {
                              "type": "string"
                            },
                            "cents": {
                              "type": "number"
                            },
                            "decimalRatio": {
                              "type": "number"
                            },
                            "stringLength": {
                              "type": "number"
                            },
                            "fretDivision": {
                              "type": "number"
                            }
                          }
                        },
                        "identifier": {
                          "$ref": "#/components/schemas/IdentifierRef",
                          "description": "The input identifier used to find this pitch class"
                        }
                      }
                    },
                    "to": {
                      "type": "object",
                      "properties": {
                        "pitchClass": {
                          "type": "object",
                          "properties": {
                            "pitchClassIndex": {
                              "type": "integer"
                            },
                            "octave": {
                              "type": "integer"
                            },
                            "noteName": {
                              "type": "string",
                              "description": "URL-safe note name"
                            },
                            "noteNameDisplay": {
                              "type": "string",
                              "description": "Display note name with diacritics"
                            },
                            "noteNameDisplayAr": {
                              "type": "string",
                              "description": "Arabic note name (if includeArabic=true)"
                            },
                            "englishName": {
                              "type": "string"
                            },
                            "solfege": {
                              "type": "string"
                            },
                            "abjadName": {
                              "type": "string"
                            },
                            "fraction": {
                              "type": "string"
                            },
                            "cents": {
                              "type": "number"
                            },
                            "decimalRatio": {
                              "type": "number"
                            },
                            "stringLength": {
                              "type": "number"
                            },
                            "fretDivision": {
                              "type": "number"
                            }
                          }
                        },
                        "identifier": {
                          "$ref": "#/components/schemas/IdentifierRef",
                          "description": "The input identifier used to find this pitch class"
                        }
                      }
                    },
                    "interval": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            }
                          ],
                          "description": "The interval in the requested unit format"
                        },
                        "unit": {
                          "type": "string",
                          "description": "The requested unit format",
                          "enum": [
                            "fraction",
                            "cents",
                            "centsFromZero",
                            "decimalRatio",
                            "stringLength",
                            "fretDivision"
                          ]
                        },
                        "allUnits": {
                          "type": "object",
                          "description": "All unit formats for reference",
                          "properties": {
                            "fraction": {
                              "type": "string"
                            },
                            "cents": {
                              "type": "number"
                            },
                            "decimalRatio": {
                              "type": "number"
                            },
                            "stringLength": {
                              "type": "number"
                            },
                            "fretDivision": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                },
                "examples": {
                  "noteNames": {
                    "summary": "Calculate interval using note names",
                    "value": {
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "idName": "ibnsina_1037",
                          "displayName": "Ibn Sīnā (1037)"
                        },
                        "startingNote": {
                          "idName": "yegah",
                          "displayName": "yegāh"
                        },
                        "referenceFrequency": 97.999
                      },
                      "from": {
                        "pitchClass": {
                          "pitchClassIndex": 0,
                          "octave": 0,
                          "noteName": "yegah",
                          "noteNameDisplay": "yegāh",
                          "englishName": "D",
                          "solfege": "re",
                          "abjadName": "د",
                          "fraction": "1/1",
                          "cents": 0,
                          "decimalRatio": 1,
                          "stringLength": 1000,
                          "fretDivision": 0
                        },
                        "identifier": {
                          "idName": "yegah",
                          "displayName": "yegāh"
                        }
                      },
                      "to": {
                        "pitchClass": {
                          "pitchClassIndex": 1,
                          "octave": 0,
                          "noteName": "dugah",
                          "noteNameDisplay": "dūgāh",
                          "englishName": "E",
                          "solfege": "mi",
                          "abjadName": "ه",
                          "fraction": "9/8",
                          "cents": 203.91,
                          "decimalRatio": 1.125,
                          "stringLength": 888.889,
                          "fretDivision": 102
                        },
                        "identifier": {
                          "idName": "dugah",
                          "displayName": "dūgāh"
                        }
                      },
                      "interval": {
                        "value": 203.91,
                        "unit": "cents",
                        "allUnits": {
                          "fraction": "9/8",
                          "cents": 203.91,
                          "decimalRatio": 1.125,
                          "stringLength": 111.111,
                          "fretDivision": 102
                        }
                      },
                      "links": {
                        "self": "/api/intervals/calculate?from=yegah&to=dugah&tuningSystem=ibnsina_1037&startingNote=yegah&unit=cents",
                        "tuningSystem": "/api/tuning-systems/ibnsina_1037",
                        "intervals": "/api/intervals?noteNames=yegah,dugah&tuningSystem=ibnsina_1037&startingNote=yegah"
                      }
                    }
                  },
                  "values": {
                    "summary": "Calculate interval using values",
                    "value": {
                      "context": {
                        "tuningSystem": {
                          "id": "ibnsina_1037",
                          "idName": "ibnsina_1037",
                          "displayName": "Ibn Sīnā (1037)"
                        },
                        "startingNote": {
                          "idName": "yegah",
                          "displayName": "yegāh"
                        },
                        "referenceFrequency": 97.999
                      },
                      "from": {
                        "pitchClass": {
                          "pitchClassIndex": 0,
                          "octave": 0,
                          "noteName": "yegah",
                          "noteNameDisplay": "yegāh",
                          "englishName": "D",
                          "solfege": "re",
                          "abjadName": "د",
                          "fraction": "1/1",
                          "cents": 0,
                          "decimalRatio": 1,
                          "stringLength": 1000,
                          "fretDivision": 0
                        },
                        "identifier": {
                          "idName": "1/1",
                          "displayName": "1/1"
                        }
                      },
                      "to": {
                        "pitchClass": {
                          "pitchClassIndex": 1,
                          "octave": 0,
                          "noteName": "dugah",
                          "noteNameDisplay": "dūgāh",
                          "englishName": "E",
                          "solfege": "mi",
                          "abjadName": "ه",
                          "fraction": "9/8",
                          "cents": 203.91,
                          "decimalRatio": 1.125,
                          "stringLength": 888.889,
                          "fretDivision": 102
                        },
                        "identifier": {
                          "idName": "9/8",
                          "displayName": "9/8"
                        }
                      },
                      "interval": {
                        "value": "9/8",
                        "unit": "fraction",
                        "allUnits": {
                          "fraction": "9/8",
                          "cents": 203.91,
                          "decimalRatio": 1.125,
                          "stringLength": 111.111,
                          "fretDivision": 102
                        }
                      },
                      "links": {
                        "self": "/api/intervals/calculate?from=1/1&to=9/8&tuningSystem=ibnsina_1037&startingNote=yegah&unit=fraction&fromType=fraction&toType=fraction",
                        "tuningSystem": "/api/tuning-systems/ibnsina_1037",
                        "intervals": "/api/intervals?noteNames=yegah,dugah&tuningSystem=ibnsina_1037&startingNote=yegah"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingParameter": {
                    "summary": "Missing required parameter",
                    "value": {
                      "error": "from parameter is required",
                      "message": "The first pitch class identifier must be provided.",
                      "hint": "Add &from=rast or &from=3/2 to your request"
                    }
                  },
                  "invalidUnit": {
                    "summary": "Invalid unit parameter",
                    "value": {
                      "error": "Invalid unit 'invalid'",
                      "message": "The unit must be one of the valid options.",
                      "validOptions": [
                        "fraction",
                        "cents",
                        "centsFromZero",
                        "decimalRatio",
                        "stringLength",
                        "fretDivision"
                      ],
                      "hint": "Use one of: fraction, cents, centsFromZero, decimalRatio, stringLength, fretDivision"
                    }
                  },
                  "invalidStartingNote": {
                    "summary": "Invalid starting note",
                    "value": {
                      "error": "Invalid startingNote 'invalid'",
                      "validOptions": [
                        "yegah",
                        "ushayran",
                        "rast"
                      ],
                      "hint": "Valid starting notes for this tuning system: yegah, ushayran, rast"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Pitch class or tuning system not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "pitchClassNotFound": {
                    "summary": "Pitch class not found",
                    "value": {
                      "error": "Pitch class 'invalid' not found",
                      "message": "Could not find a pitch class matching 'invalid' in tuning system 'ibnsina_1037' with starting note 'yegah'.",
                      "hint": "Use /api/pitch-classes/note-names to see all valid note names, or ensure the value matches exactly a pitch class value in the tuning system"
                    }
                  },
                  "tuningSystemNotFound": {
                    "summary": "Tuning system not found",
                    "value": {
                      "error": "Tuning system 'invalid' not found",
                      "hint": "Use /api/tuning-systems to see all available tuning systems"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/sources": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List all bibliographic sources",
        "description": "Return all bibliographic sources (books, articles, theses) with comprehensive metadata.\n\n- Includes titles, contributors, publication information, and version timestamps\n- Sources document the historical and scholarly foundation for the archive's musical data\n- All sources include common fields (edition, publication date, URL, etc.)\n- Type-specific fields are included based on sourceType:\n  - Books: publisher, place, ISBN, original publication date\n  - Articles: journal, volume, issue, page range, DOI\n  - Theses: degree type, university, department, database information\n",
        "operationId": "listSources",
        "parameters": [
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "List of sources retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "data"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Total number of sources"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SourceResponse"
                      }
                    }
                  }
                },
                "examples": {
                  "comprehensive": {
                    "summary": "Comprehensive source data with all fields",
                    "value": {
                      "count": 2,
                      "data": [
                        {
                          "id": "al-Khulʿī-(1904/2011)",
                          "displayName": "al-Khulʿī-(1904/2011)",
                          "sourceType": "Book",
                          "title": "Kitāb al-Mūsiqā al-Sharqī",
                          "titleAr": "كتاب الموسيقى الشرقي",
                          "contributors": [
                            {
                              "type": "Author",
                              "firstName": "Mohammad Kāmil",
                              "lastName": "al-Khulʿī",
                              "firstNameAr": "محمد كامل",
                              "lastNameAr": "الخلعي"
                            }
                          ],
                          "edition": "",
                          "editionAr": "",
                          "publicationDate": "2011",
                          "publicationDateAr": "٢٠١١",
                          "url": "https://www.hindawi.org/books/46319638/",
                          "dateAccessed": "21-05-2025",
                          "version": "2025-10-18T19:50:31.664Z",
                          "originalPublicationDate": "1904",
                          "originalPublicationDateAr": "١٩٠٤",
                          "publisher": "Hindawi Foundation for Education and Culture",
                          "publisherAr": "مؤسسة هنداوي للتعليم والثقافة",
                          "place": "Cairo",
                          "placeAr": "القاهرة",
                          "ISBN": "9789776416543"
                        },
                        {
                          "id": "Farmer-(1937)",
                          "displayName": "Farmer-(1937)",
                          "sourceType": "Article",
                          "title": "The Lute Scale of Avicenna",
                          "titleAr": "سلم العود لإبن سينا",
                          "contributors": [
                            {
                              "type": "Author",
                              "firstName": "Henry George",
                              "lastName": "Farmer",
                              "firstNameAr": "هنري جورج",
                              "lastNameAr": "فارمر"
                            }
                          ],
                          "edition": "",
                          "editionAr": "",
                          "publicationDate": "1937",
                          "publicationDateAr": "١٩٣٧",
                          "url": "",
                          "dateAccessed": "",
                          "version": "2025-10-18T19:50:31.664Z",
                          "journal": "The Journal of the Royal Asiatic Society of Great Britain and Ireland",
                          "journalAr": "مجلة الجمعية الملكية الآسيوية في بريطانيا العظمى وأيرلندا",
                          "volume": "2",
                          "volumeAr": "٢",
                          "issue": "",
                          "issueAr": "",
                          "pageRange": "245–257",
                          "pageRangeAr": "٢٤٥-٢٥٧",
                          "DOI": ""
                        },
                        {
                          "id": "Allami-(2022)",
                          "displayName": "Allami-(2022)",
                          "sourceType": "Thesis",
                          "title": "Échos-monde: Towards a hybrid repertoire of contemporary and experimental acoustic, electroacoustic and electronic Arabic music",
                          "titleAr": "‎عالم الأصداء: نحو رصيدٍ هجينٍ للموسيقى العربية المعاصرة والتجريبية، صوتياً وكهروصوتياً وإلكترونياً",
                          "contributors": [
                            {
                              "type": "Author",
                              "firstName": "Khyam",
                              "lastName": "Allami",
                              "firstNameAr": "خيّام",
                              "lastNameAr": "اللامي"
                            }
                          ],
                          "edition": "",
                          "editionAr": "",
                          "publicationDate": "2022",
                          "publicationDateAr": "",
                          "url": "https://www.open-access.bcu.ac.uk/14036/",
                          "dateAccessed": "16-10-2025",
                          "version": "2025-10-23T22:32:56.276Z",
                          "degreeType": "PhD Dissertation",
                          "degreeTypeAr": "أطروحة دكتوراه",
                          "university": "Birmingham City University",
                          "universityAr": "جامعة برمنغهام سيتي",
                          "department": "Royal Birmingham Conservatoire",
                          "departmentAr": "معهد برمنغهام الملكي",
                          "databaseIdentifier": "",
                          "databaseName": ""
                        }
                      ],
                      "meta": {
                        "total": 17
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/sources/{id}": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "Get a single bibliographic source",
        "description": "Return detailed information for a single bibliographic source by ID.\n\n- Returns comprehensive bibliographic metadata for the specified source\n- Includes all common fields (title, contributors, publication date, etc.)\n- Includes type-specific fields based on sourceType:\n  - Books: publisher, place, ISBN, original publication date\n  - Articles: journal, volume, issue, page range, DOI\n  - Theses: degree type, university, department, database information\n- Supports bilingual responses (English/Arabic) via includeArabic parameter\n",
        "operationId": "getSource",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique identifier for the bibliographic source.\n\nExamples:\n- `al-Khuli-(2011)` - Book source ID (URL-safe, diacritics removed)\n- `Farmer-(1937)` - Article source ID\n- `Allami-(2022)` - Thesis source ID\n\n**Note**: Source IDs use only the publication date (not original publication date)\nand are URL-safe with diacritics removed for compatibility.\n\nUse the `/api/sources` endpoint to retrieve all available source IDs.\n",
            "schema": {
              "type": "string"
            },
            "example": "Farmer-(1937)"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., titleAr, firstNameAr, lastNameAr)\n- Contributors get Arabic name versions in firstNameAr and lastNameAr fields\n- Type-specific fields get Arabic versions (e.g., publisherAr, journalAr, universityAr)\n- Display name gets Arabic version in displayNameAr field\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Source retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "$ref": "#/components/schemas/SourceResponse"
                    }
                  }
                },
                "examples": {
                  "book": {
                    "summary": "Book source example",
                    "value": {
                      "source": {
                        "id": "al-Khuli-(2011)",
                        "displayName": "al-Khuli-(2011)",
                        "sourceType": "Book",
                        "title": "Kitāb al-Mūsiqā al-Sharqī",
                        "contributors": [
                          {
                            "type": "Author",
                            "firstName": "Mohammad Kāmil",
                            "lastName": "al-Khulʿī"
                          }
                        ],
                        "edition": "",
                        "publicationDate": "2011",
                        "url": "https://www.hindawi.org/books/46319638/",
                        "dateAccessed": "21-05-2025",
                        "version": "2025-10-18T19:50:31.664Z",
                        "originalPublicationDate": "1904",
                        "publisher": "Hindawi Foundation for Education and Culture",
                        "place": "Cairo",
                        "ISBN": "9789776416543"
                      }
                    }
                  },
                  "article": {
                    "summary": "Article source example",
                    "value": {
                      "source": {
                        "id": "Farmer-(1937)",
                        "displayName": "Farmer-(1937)",
                        "sourceType": "Article",
                        "title": "The Lute Scale of Avicenna",
                        "contributors": [
                          {
                            "type": "Author",
                            "firstName": "Henry George",
                            "lastName": "Farmer"
                          }
                        ],
                        "edition": "",
                        "publicationDate": "1937",
                        "url": "",
                        "dateAccessed": "",
                        "version": "2025-10-18T19:50:31.664Z",
                        "journal": "The Journal of the Royal Asiatic Society of Great Britain and Ireland",
                        "volume": "2",
                        "issue": "",
                        "pageRange": "245–257",
                        "DOI": ""
                      }
                    }
                  },
                  "thesis": {
                    "summary": "Thesis source example",
                    "value": {
                      "source": {
                        "id": "Allami-(2022)",
                        "displayName": "Allami-(2022)",
                        "sourceType": "Thesis",
                        "title": "Échos-monde: Towards a hybrid repertoire of contemporary and experimental acoustic, electroacoustic and electronic Arabic music",
                        "contributors": [
                          {
                            "type": "Author",
                            "firstName": "Khyam",
                            "lastName": "Allami"
                          }
                        ],
                        "edition": "",
                        "publicationDate": "2022",
                        "url": "https://www.open-access.bcu.ac.uk/14036/",
                        "dateAccessed": "16-10-2025",
                        "version": "2025-10-23T22:32:56.276Z",
                        "degreeType": "PhD Dissertation",
                        "university": "Birmingham City University",
                        "department": "Royal Birmingham Conservatoire",
                        "databaseIdentifier": "",
                        "databaseName": ""
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid or missing source ID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    },
                    "example": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "error": "No source ID provided",
                  "hint": "Please specify a source ID",
                  "example": "/api/sources/Farmer-(1937)"
                }
              }
            }
          },
          "404": {
            "description": "Source not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "error": "Source 'invalid-id' not found",
                  "hint": "Use /api/sources to see all available sources"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/sources/{id}/tuning-systems": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List tuning systems by source",
        "description": "Returns all tuning systems that reference the specified source.\n\nA tuning system is included if any of its sourcePageReferences match the source ID.\nThis endpoint provides an easy way to see which tuning systems have been derived from a specific source.\n",
        "operationId": "listTuningSystemsBySource",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique identifier for the bibliographic source.\n\nUse the `/api/sources` endpoint to retrieve all available source IDs.\n",
            "schema": {
              "type": "string"
            },
            "example": "Farmer-(1937)"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Tuning systems retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/EntityRef"
                        }
                      }
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tuningSystem": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "sourceReferences": {
                            "type": "array",
                            "description": "Page references for this source within the tuning system",
                            "items": {
                              "type": "object",
                              "properties": {
                                "page": {
                                  "type": "string",
                                  "description": "Page number or range where the tuning system is documented"
                                }
                              }
                            }
                          },
                          "startingNotes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "links": {
                            "$ref": "#/components/schemas/Links"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Source not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/sources/{id}/maqamat": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List maqamat by source",
        "description": "Returns all maqamat that reference the specified source.\n\nA maqam is included if any of its sourcePageReferences match the source ID.\nThis endpoint provides an easy way to see which maqamat have been documented in a specific source.\n",
        "operationId": "listMaqamatBySource",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique identifier for the bibliographic source.\n\nUse the `/api/sources` endpoint to retrieve all available source IDs.\n",
            "schema": {
              "type": "string"
            },
            "example": "Farmer-(1937)"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Maqamat retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/EntityRef"
                        }
                      }
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "maqam": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "sourceReferences": {
                            "type": "array",
                            "description": "Page references for this source within the maqam",
                            "items": {
                              "type": "object",
                              "properties": {
                                "page": {
                                  "type": "string",
                                  "description": "Page number or range where the maqam is documented"
                                }
                              }
                            }
                          },
                          "links": {
                            "$ref": "#/components/schemas/Links"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Source not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/sources/{id}/ajnas": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List ajnas by source",
        "description": "Returns all ajnas that reference the specified source.\n\nA jins is included if any of its SourcePageReferences match the source ID.\nThis endpoint provides an easy way to see which ajnas have been documented in a specific source.\n",
        "operationId": "listAjnasBySource",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique identifier for the bibliographic source.\n\nUse the `/api/sources` endpoint to retrieve all available source IDs.\n",
            "schema": {
              "type": "string"
            },
            "example": "Farmer-(1937)"
          },
          {
            "name": "includeArabic",
            "in": "query",
            "required": false,
            "description": "Return bilingual responses with Arabic script when true.\n\nWhen true:\n- All English/transliteration fields remain unchanged\n- Arabic versions are added with \"Ar\" suffix (e.g., displayNameAr, noteNameDisplayAr)\n- Note names, maqām names, and jins names get Arabic versions in *Ar fields\n- Comments get Arabic versions in commentsAr if available\n- Tuning system display names get Arabic versions in displayNameAr if available\n- Source metadata gets Arabic versions in *Ar fields (titleAr, firstNameAr, etc.)\n",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Ajnas retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/EntityRef"
                        }
                      }
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "jins": {
                            "$ref": "#/components/schemas/EntityRef"
                          },
                          "sourceReferences": {
                            "type": "array",
                            "description": "Page references for this source within the jins",
                            "items": {
                              "type": "object",
                              "properties": {
                                "page": {
                                  "type": "string",
                                  "description": "Page number or range where the jins is documented"
                                }
                              }
                            }
                          },
                          "links": {
                            "$ref": "#/components/schemas/Links"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Source not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MaqamatListResponse": {
        "type": "object",
        "required": [
          "count",
          "data"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Total number of maqāmāt",
            "example": 60
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MaqamMetadata"
            }
          }
        }
      },
      "MaqamMetadata": {
        "type": "object",
        "required": [
          "id",
          "idName",
          "displayName",
          "version",
          "familyId",
          "familyDisplay",
          "tonicId",
          "tonicDisplay",
          "numberOfPitchClasses",
          "isOctaveRepeating",
          "hasAsymmetricDescending",
          "hasSuyur",
          "availableInTuningSystems",
          "tuningSystemsAvailability",
          "maqamDetailsUrl"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Numeric ID",
            "example": "29"
          },
          "idName": {
            "type": "string",
            "description": "URL-safe identifier",
            "example": "maqam_yegah"
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable name with diacritics",
            "example": "maqām yegāh"
          },
          "version": {
            "type": "string",
            "description": "Version timestamp (ISO 8601)",
            "example": "2025-10-18T19:41:17.132Z"
          },
          "familyId": {
            "type": "string",
            "description": "URL-safe family identifier",
            "example": "no_jins"
          },
          "familyDisplay": {
            "type": "string",
            "description": "Human-readable family name",
            "example": "no jins"
          },
          "tonicId": {
            "type": "string",
            "description": "URL-safe tonic name",
            "example": "yegah"
          },
          "tonicDisplay": {
            "type": "string",
            "description": "Tonic name with diacritics",
            "example": "yegāh"
          },
          "numberOfPitchClasses": {
            "type": "integer",
            "description": "Count of pitch classes in ascending sequence",
            "example": 7
          },
          "isOctaveRepeating": {
            "type": "boolean",
            "description": "True when numberOfPitchClasses ≤ 7",
            "example": true
          },
          "hasAsymmetricDescending": {
            "type": "boolean",
            "description": "True when descending sequence differs from ascending",
            "example": true
          },
          "hasSuyur": {
            "type": "boolean",
            "description": "True when suyūr (melodic paths) are documented",
            "example": true
          },
          "availableInTuningSystems": {
            "type": "integer",
            "description": "Count of tuning systems supporting this maqām",
            "example": 4
          },
          "tuningSystemsAvailability": {
            "type": "array",
            "description": "Tuning systems where maqām is available with their valid tuning system starting notes (simplified structure without transposition counts for list endpoint)",
            "items": {
              "type": "object",
              "properties": {
                "tuningSystemId": {
                  "type": "string",
                  "example": "alfarabi_950g"
                },
                "tuningSystemStartingNoteNames": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "ʿushayrān"
                  ]
                }
              }
            },
            "example": [
              {
                "tuningSystemId": "alfarabi_950g",
                "tuningSystemStartingNoteNames": [
                  "ʿushayrān"
                ]
              },
              {
                "tuningSystemId": "ibnsina_1037",
                "tuningSystemStartingNoteNames": [
                  "ʿushayrān",
                  "yegāh"
                ]
              }
            ]
          },
          "maqamDetailsUrl": {
            "type": "string",
            "description": "Relative URL to maqām detail endpoint",
            "example": "/api/maqamat/maqam_yegah"
          },
          "sources": {
            "type": "array",
            "description": "Bibliographic source references for this maqām",
            "items": {
              "type": "object",
              "properties": {
                "sourceId": {
                  "type": "string",
                  "description": "URL-safe source identifier",
                  "example": "al-Shawwa-(1946)"
                },
                "page": {
                  "type": "string",
                  "description": "Page number or range where the maqām is documented",
                  "example": "49"
                }
              }
            },
            "example": [
              {
                "sourceId": "al-Shawwa-(1946)",
                "page": "49"
              }
            ]
          }
        }
      },
      "TuningSystemAvailability": {
        "type": "object",
        "required": [
          "tuningSystemId",
          "tuningSystemDisplayName",
          "tuningSystemStartingNoteNames",
          "tuningSystemStartingNoteNamesIds"
        ],
        "properties": {
          "tuningSystemId": {
            "type": "string",
            "description": "Tuning system identifier (e.g., 'ibnsina_1037', 'alfarabi_950g', 'meshshaqa_1899')",
            "example": "ibnsina_1037"
          },
          "tuningSystemDisplayName": {
            "type": "string",
            "description": "Display name formatted as \"Creator (Year) Title\" (e.g., \"Ibn Sīnā (1037) 7-Fret Oud 17-Tone\")",
            "example": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone"
          },
          "tuningSystemStartingNoteNames": {
            "type": "array",
            "description": "Tuning system starting note names where this maqām is available (display values with diacritics). These represent different theoretical frameworks, not simple transpositions.",
            "items": {
              "type": "string"
            },
            "example": [
              "ʿushayrān",
              "yegāh"
            ]
          },
          "tuningSystemStartingNoteNamesIds": {
            "type": "array",
            "description": "URL-safe identifiers for tuning system starting note names (for use in API calls)",
            "items": {
              "type": "string"
            },
            "example": [
              "ushayran",
              "yegah"
            ]
          }
        }
      },
      "MaqamDetailResponse": {
        "type": "object",
        "required": [
          "maqam",
          "context",
          "pitchData",
          "ajnas"
        ],
        "properties": {
          "maqam": {
            "$ref": "#/components/schemas/MaqamMetadata"
          },
          "context": {
            "$ref": "#/components/schemas/MaqamContext"
          },
          "pitchData": {
            "$ref": "#/components/schemas/PitchData"
          },
          "ajnas": {
            "$ref": "#/components/schemas/AjnasData",
            "description": "Always included for maqām analysis"
          },
          "intervals": {
            "$ref": "#/components/schemas/IntervalsData",
            "description": "Optional - included when includeIntervals=true"
          },
          "modulations": {
            "$ref": "#/components/schemas/ModulationsData",
            "description": "Optional - included when includeModulations=true"
          },
          "suyur": {
            "type": "array",
            "description": "Optional - included when includeSuyur=true",
            "items": {
              "$ref": "#/components/schemas/Sayr"
            }
          }
        }
      },
      "JinsDetailResponse": {
        "type": "object",
        "required": [
          "jins",
          "context",
          "pitchData"
        ],
        "properties": {
          "jins": {
            "type": "object",
            "required": [
              "id",
              "idName",
              "displayName",
              "version",
              "tonicId",
              "tonicName",
              "transposition",
              "numberOfTranspositions",
              "numberOfPitchClasses",
              "pitchClassDataType",
              "includeIntervals"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Numeric identifier for the jins"
              },
              "idName": {
                "type": "string",
                "description": "URL-safe identifier for the jins"
              },
              "displayName": {
                "type": "string",
                "description": "Display name with diacritics"
              },
              "version": {
                "type": "string",
                "description": "ISO 8601 timestamp of last modification"
              },
              "tonicId": {
                "type": "string",
                "description": "URL-safe tonic note identifier"
              },
              "tonicName": {
                "type": "string",
                "description": "Tonic note name with diacritics"
              },
              "transposition": {
                "type": "boolean",
                "description": "Whether this is a transposition from the original tonic"
              },
              "originalTonicId": {
                "type": "string",
                "description": "Original tonic identifier (present only if transposed)"
              },
              "originalTonicName": {
                "type": "string",
                "description": "Original tonic name (present only if transposed)"
              },
              "transposedTonicId": {
                "type": "string",
                "description": "Transposed tonic identifier (present only if transposed)"
              },
              "transposedTonicName": {
                "type": "string",
                "description": "Transposed tonic name (present only if transposed)"
              },
              "numberOfTranspositions": {
                "type": "integer",
                "description": "Total number of available transpositions"
              },
              "numberOfPitchClasses": {
                "type": "integer",
                "description": "Number of pitch classes in this jins"
              },
              "commentsEnglish": {
                "type": "string",
                "nullable": true,
                "description": "English commentary"
              },
              "commentsArabic": {
                "type": "string",
                "nullable": true,
                "description": "Arabic commentary"
              },
              "sources": {
                "type": "array",
                "description": "Bibliographic source references",
                "items": {
                  "type": "object",
                  "properties": {
                    "sourceId": {
                      "type": "string"
                    },
                    "page": {
                      "type": "string"
                    }
                  }
                }
              },
              "pitchClassDataType": {
                "type": "string",
                "description": "Format used for pitch class data"
              },
              "includeIntervals": {
                "type": "boolean",
                "description": "Whether intervals are included"
              }
            }
          },
          "context": {
            "$ref": "#/components/schemas/MaqamContext"
          },
          "pitchData": {
            "type": "array",
            "description": "Pitch class sequence (ajnās are unidirectional, not ascending/descending)",
            "items": {
              "$ref": "#/components/schemas/PitchClass"
            }
          },
          "intervals": {
            "type": "array",
            "description": "Optional - included when includeIntervals=true. Interval data between consecutive pitch classes.",
            "items": {
              "type": "object",
              "description": "Interval data (fields vary by format parameter)"
            }
          }
        }
      },
      "SourceResponse": {
        "type": "object",
        "description": "Comprehensive bibliographic source information. Includes common fields for all source types\nand type-specific fields based on sourceType (Book, Article, or Thesis). Arabic-language\nfields are suffixed with \"Ar\" and are returned only when the `includeArabic` parameter is true.\n",
        "required": [
          "id",
          "displayName",
          "sourceType",
          "title",
          "contributors",
          "edition",
          "publicationDate",
          "url",
          "dateAccessed",
          "version"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the source"
          },
          "displayName": {
            "type": "string",
            "description": "Formatted citation string (e.g., \"Author (Year) Title\")"
          },
          "displayNameAr": {
            "type": "string",
            "description": "Arabic formatted citation string (present when includeArabic=true)"
          },
          "sourceType": {
            "type": "string",
            "enum": [
              "Book",
              "Article",
              "Thesis"
            ],
            "description": "Type discriminator for the source"
          },
          "title": {
            "type": "string",
            "description": "Source title in English/transliteration"
          },
          "titleAr": {
            "type": "string",
            "description": "Source title in Arabic (present when includeArabic=true)"
          },
          "contributors": {
            "type": "array",
            "description": "Array of contributors (authors, editors, translators, etc.)",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Contributor role (e.g., \"Author\", \"Editor\", \"Reviewer\")"
                },
                "firstName": {
                  "type": "string",
                  "description": "First name in English/transliteration"
                },
                "lastName": {
                  "type": "string",
                  "description": "Last name in English/transliteration"
                },
                "firstNameAr": {
                  "type": "string",
                  "description": "First name in Arabic (present when includeArabic=true)"
                },
                "lastNameAr": {
                  "type": "string",
                  "description": "Last name in Arabic (present when includeArabic=true)"
                }
              }
            }
          },
          "edition": {
            "type": "string",
            "description": "Edition information in English/transliteration"
          },
          "editionAr": {
            "type": "string",
            "description": "Edition information in Arabic (present when includeArabic=true)"
          },
          "publicationDate": {
            "type": "string",
            "description": "Publication date (string, e.g., \"2025\" or ISO date)"
          },
          "publicationDateAr": {
            "type": "string",
            "description": "Publication date in Arabic (present when includeArabic=true)"
          },
          "url": {
            "type": "string",
            "description": "URL for online sources (empty string if not applicable)"
          },
          "dateAccessed": {
            "type": "string",
            "description": "Date when online source was accessed (empty string if not applicable)"
          },
          "version": {
            "type": "string",
            "description": "ISO 8601 timestamp of last modification"
          },
          "originalPublicationDate": {
            "type": "string",
            "description": "Original publication date (for reprints and editions)"
          },
          "originalPublicationDateAr": {
            "type": "string",
            "description": "Original publication date in Arabic (present when includeArabic=true)"
          },
          "publisher": {
            "type": "string",
            "description": "Publisher name"
          },
          "publisherAr": {
            "type": "string",
            "description": "Publisher name in Arabic (present when includeArabic=true)"
          },
          "place": {
            "type": "string",
            "description": "Publication place"
          },
          "placeAr": {
            "type": "string",
            "description": "Publication place in Arabic (present when includeArabic=true)"
          },
          "ISBN": {
            "type": "string",
            "description": "International Standard Book Number"
          },
          "journal": {
            "type": "string",
            "description": "Journal name"
          },
          "journalAr": {
            "type": "string",
            "description": "Journal name in Arabic (present when includeArabic=true)"
          },
          "volume": {
            "type": "string",
            "description": "Volume number"
          },
          "volumeAr": {
            "type": "string",
            "description": "Volume number in Arabic (present when includeArabic=true)"
          },
          "issue": {
            "type": "string",
            "description": "Issue number"
          },
          "issueAr": {
            "type": "string",
            "description": "Issue number in Arabic (present when includeArabic=true)"
          },
          "pageRange": {
            "type": "string",
            "description": "Page range (e.g., \"45–67\")"
          },
          "pageRangeAr": {
            "type": "string",
            "description": "Page range in Arabic (present when includeArabic=true)"
          },
          "DOI": {
            "type": "string",
            "description": "Digital Object Identifier"
          },
          "degreeType": {
            "type": "string",
            "description": "Type of degree (e.g., \"Master's thesis\", \"PhD dissertation\")"
          },
          "degreeTypeAr": {
            "type": "string",
            "description": "Type of degree in Arabic (present when includeArabic=true)"
          },
          "university": {
            "type": "string",
            "description": "University or institution name"
          },
          "universityAr": {
            "type": "string",
            "description": "University or institution name in Arabic (present when includeArabic=true)"
          },
          "department": {
            "type": "string",
            "description": "Department name"
          },
          "departmentAr": {
            "type": "string",
            "description": "Department name in Arabic (present when includeArabic=true)"
          },
          "databaseIdentifier": {
            "type": "string",
            "description": "Database identifier (e.g., ProQuest ID)"
          },
          "databaseName": {
            "type": "string",
            "description": "Name of the database (e.g., \"ProQuest\", \"PQDT\")"
          }
        }
      },
      "SourceDetailResponse": {
        "type": "object",
        "required": [
          "source"
        ],
        "properties": {
          "source": {
            "$ref": "#/components/schemas/SourceResponse"
          }
        }
      },
      "MaqamContext": {
        "type": "object",
        "required": [
          "tuningSystem"
        ],
        "properties": {
          "tuningSystem": {
            "$ref": "#/components/schemas/TuningSystemMetadata"
          }
        }
      },
      "TuningSystemMetadata": {
        "type": "object",
        "required": [
          "id",
          "displayName",
          "numberOfPitchClassesSingleOctave",
          "tuningSystemStartingNoteNames",
          "tuningSystemStartingNoteNamesIds"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "URL-safe tuning system identifier",
            "example": "ibnsina_1037"
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable name",
            "example": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone"
          },
          "version": {
            "type": "string",
            "description": "Version timestamp (ISO 8601)",
            "example": "2025-10-18T19:42:23.643Z"
          },
          "year": {
            "type": "string",
            "description": "Year the tuning system was documented or created",
            "example": "1037"
          },
          "numberOfPitchClassesSingleOctave": {
            "type": "integer",
            "description": "Number of pitch classes per octave",
            "example": 17
          },
          "tuningSystemStartingNoteNames": {
            "type": "array",
            "description": "Available tuning system starting note names (first note in each note name set) with diacritics. These represent different theoretical traditions (ʿushayrān for oud tuning, yegāh for monochord measurements, rāst for pedagogical frameworks).",
            "items": {
              "type": "string"
            },
            "example": [
              "ʿushayrān",
              "yegāh"
            ]
          },
          "tuningSystemStartingNoteNamesIds": {
            "type": "array",
            "description": "URL-safe identifiers for tuning system starting note names (for use in API calls)",
            "items": {
              "type": "string"
            },
            "example": [
              "ushayran",
              "yegah"
            ]
          },
          "numberOfPitchClassesAllOctaves": {
            "type": "integer",
            "description": "Total pitch-class count across available octaves (used for non-octave-repeating maqāmāt)",
            "example": 51
          },
          "originalValueType": {
            "type": "string",
            "description": "The original numeric representation for pitch classes in this tuning system",
            "example": "fraction"
          },
          "startingNoteName": {
            "type": "string",
            "description": "The selected tuning system starting note for this context (preferred over deprecated context.startingNote)",
            "example": "ushayran"
          }
        }
      },
      "PitchData": {
        "type": "object",
        "required": [
          "ascending",
          "descending"
        ],
        "properties": {
          "ascending": {
            "type": "array",
            "description": "Ascending scale pitch classes",
            "items": {
              "$ref": "#/components/schemas/PitchClass"
            }
          },
          "descending": {
            "type": "array",
            "description": "Descending scale pitch classes",
            "items": {
              "$ref": "#/components/schemas/PitchClass"
            }
          }
        }
      },
      "PitchClass": {
        "type": "object",
        "description": "Pitch class data (fields vary by format parameter)",
        "properties": {
          "pitchClassIndex": {
            "type": "integer",
            "description": "Index in tuning system",
            "example": 0
          },
          "octave": {
            "type": "integer",
            "description": "Octave number (0, 1, 2, or 3) indicating which octave this pitch class belongs to",
            "example": 1
          },
          "scaleDegree": {
            "type": "string",
            "description": "Roman numeral maqām degree",
            "example": "I"
          },
          "noteName": {
            "type": "string",
            "description": "URL-safe note name",
            "example": "ushayran"
          },
          "noteNameDisplay": {
            "type": "string",
            "description": "Note name with diacritics",
            "example": "ʿushayrān"
          },
          "englishName": {
            "type": "string",
            "description": "English transliteration",
            "example": "ushayran"
          },
          "abjadName": {
            "type": "string",
            "description": "Arabic script name",
            "example": "عشيران"
          },
          "frequency": {
            "type": "number",
            "format": "float",
            "description": "Frequency in Hz (when pitchClassDataType=frequency or all)",
            "example": 97.999
          },
          "cents": {
            "type": "number",
            "format": "float",
            "description": "Cents above reference (when pitchClassDataType=cents or all)",
            "example": 0
          },
          "fraction": {
            "type": "string",
            "description": "Interval fraction ratio (when pitchClassDataType=fraction or all)",
            "example": "1/1"
          },
          "decimalRatio": {
            "type": "number",
            "format": "float",
            "description": "Decimal frequency ratio (when pitchClassDataType=decimalRatio or all)",
            "example": 1
          },
          "stringLength": {
            "type": "number",
            "format": "float",
            "description": "Relative string length (when pitchClassDataType=stringLength or all)",
            "example": 1
          },
          "midiNoteDecimal": {
            "type": "number",
            "format": "float",
            "description": "MIDI note with decimal cents (when format=midi or all)",
            "example": 38
          },
          "midiNotePlusCentsDeviation": {
            "type": "string",
            "description": "MIDI note ± cents deviation (when format=all)",
            "example": "D2 +0.0"
          },
          "centsDeviation": {
            "type": "number",
            "format": "float",
            "description": "Cents deviation from equal temperament (when format=all)",
            "example": 0
          },
          "ipnReferenceNoteName": {
            "type": "string",
            "description": "IPN reference note (when format=all)",
            "example": "D2"
          }
        }
      },
      "EntityRef": {
        "type": "object",
        "required": [
          "id",
          "idName",
          "displayName"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Numeric or canonical identifier"
          },
          "idName": {
            "type": "string",
            "description": "URL-safe identifier"
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable name with diacritics and transposition suffixes when applicable"
          }
        }
      },
      "IdentifierRef": {
        "type": "object",
        "required": [
          "idName",
          "displayName"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Optional numeric or canonical identifier"
          },
          "idName": {
            "type": "string",
            "description": "URL-safe identifier",
            "example": "rast"
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable name with diacritics",
            "example": "rāst"
          },
          "displayNameAr": {
            "type": "string",
            "description": "Arabic display name (present when includeArabic=true)",
            "example": "راست"
          }
        }
      },
      "Links": {
        "type": "object",
        "description": "Navigation links for related endpoints",
        "properties": {
          "self": {
            "type": "string",
            "description": "Current endpoint URL"
          },
          "detail": {
            "type": "string",
            "description": "Link to detail endpoint"
          },
          "availability": {
            "type": "string",
            "description": "Link to availability endpoint"
          },
          "compare": {
            "type": "string",
            "description": "Link to compare endpoint"
          },
          "intervals": {
            "type": "string",
            "description": "Link to intervals endpoint"
          }
        }
      },
      "AjnasData": {
        "type": "object",
        "required": [
          "ascending",
          "descending"
        ],
        "properties": {
          "ascending": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/EntityRef"
                },
                {
                  "type": "null"
                }
              ]
            },
            "description": "Note-name keyed map of ajnās present at each ascending maqām degree",
            "example": {
              "rast": {
                "id": "3",
                "idName": "jins_rast",
                "displayName": "jins rāst"
              },
              "dugah": null
            }
          },
          "descending": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/EntityRef"
                },
                {
                  "type": "null"
                }
              ]
            },
            "description": "Note-name keyed map of ajnās present at each descending maqām degree",
            "example": {
              "kurd": {
                "id": "9",
                "idName": "jins_kurd",
                "displayName": "jins kurd"
              },
              "nahawand": {
                "id": "4",
                "idName": "jins_nahawand",
                "displayName": "jins nahāwand"
              }
            }
          }
        },
        "description": "Ajnās present on each maqām degree, keyed by standardized note names. Values are full entity objects\n`{ id, idName, displayName }` when a jins is present, or `null` when no jins is assigned.\n"
      },
      "IntervalsData": {
        "type": "object",
        "properties": {
          "ascending": {
            "type": "array",
            "description": "Interval data between ascending maqām degrees",
            "items": {
              "type": "object",
              "properties": {
                "fromDegree": {
                  "type": "string"
                },
                "toDegree": {
                  "type": "string"
                },
                "cents": {
                  "type": "number"
                },
                "ratio": {
                  "type": "number"
                }
              }
            }
          },
          "descending": {
            "type": "array",
            "description": "Interval data between descending maqām degrees",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "ModulationsData": {
        "type": "object",
        "description": "Modulation networks organized by note name (darajat al-istiqrār), not technical degrees",
        "properties": {
          "maqamat": {
            "type": "array",
            "description": "Maqām modulations organized by note name, each entry includes the maqām degree, note name, pitch class index, count, and list of available modulations",
            "items": {
              "type": "object",
              "required": [
                "maqamDegree",
                "noteNameId",
                "noteNameDisplay",
                "count",
                "modulations"
              ],
              "properties": {
                "maqamDegree": {
                  "type": "string",
                  "description": "Maqām degree in Roman numerals (I, II, III, etc.)",
                  "example": "I"
                },
                "noteNameId": {
                  "type": "string",
                  "description": "URL-safe note name identifier (darajat al-istiqrār)",
                  "example": "rast"
                },
                "noteNameDisplay": {
                  "type": "string",
                  "description": "Display note name with diacritics",
                  "example": "rāst"
                },
                "pitchClassIndex": {
                  "type": "integer",
                  "description": "Pitch class index within the tuning system (0-based)",
                  "example": 4
                },
                "count": {
                  "type": "integer",
                  "description": "Number of available modulations at this degree",
                  "example": 8
                },
                "maqamDegreeDirection": {
                  "type": "string",
                  "enum": [
                    "ascending",
                    "descending"
                  ],
                  "description": "Direction for degree VI modulations (only present when applicable)",
                  "example": "ascending"
                },
                "modulations": {
                  "type": "array",
                  "description": "List of maqāmāt available for modulation at this note name",
                  "items": {
                    "$ref": "#/components/schemas/EntityRef"
                  }
                }
              }
            }
          },
          "ajnas": {
            "type": "array",
            "description": "Jins modulations organized by note name, each entry includes the jins degree, note name, pitch class index, count, and list of available modulations",
            "items": {
              "type": "object",
              "required": [
                "jinsDegree",
                "noteNameId",
                "noteNameDisplay",
                "count",
                "modulations"
              ],
              "properties": {
                "jinsDegree": {
                  "type": "string",
                  "description": "Maqām degree in Roman numerals where jins modulation occurs",
                  "example": "I"
                },
                "noteNameId": {
                  "type": "string",
                  "description": "URL-safe note name identifier (darajat al-istiqrār)",
                  "example": "rast"
                },
                "noteNameDisplay": {
                  "type": "string",
                  "description": "Display note name with diacritics",
                  "example": "rāst"
                },
                "pitchClassIndex": {
                  "type": "integer",
                  "description": "Pitch class index within the tuning system (0-based)",
                  "example": 4
                },
                "count": {
                  "type": "integer",
                  "description": "Number of available modulations at this degree",
                  "example": 5
                },
                "modulations": {
                  "type": "array",
                  "description": "List of ajnās available for modulation at this note name",
                  "items": {
                    "$ref": "#/components/schemas/EntityRef"
                  }
                }
              }
            }
          }
        }
      },
      "Sayr": {
        "type": "object",
        "description": "Melodic path (sayr) through the maqām",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "MaqamNode": {
        "type": "object",
        "description": "Represents a node in the modulation graph - a unique (maqamId, tonic) combination.\n\n**Important**: For transposed maqāmāt, use `baseMaqamIdName` + `tonicId` for queries.\nThe `maqamIdName` includes transposition suffix (e.g., \"maqam_nahawand_al-kurdan\") for display.\n",
        "required": [
          "maqamId",
          "baseMaqamIdName",
          "maqamIdName",
          "maqamDisplayName",
          "tonicId",
          "tonicDisplay",
          "isTransposition"
        ],
        "properties": {
          "maqamId": {
            "type": "string",
            "description": "Numeric ID of the maqam",
            "example": "1"
          },
          "baseMaqamIdName": {
            "type": "string",
            "description": "**Stable** base identifier for the maqam (without transposition suffix).\nUse this + tonicId for API queries to find specific transpositions.\nExample: \"maqam_nahawand\" (same for all transpositions of nahāwand)\n",
            "example": "maqam_rast"
          },
          "maqamIdName": {
            "type": "string",
            "description": "**Display** identifier that includes transposition suffix for taṣwīr forms.\nOriginal forms (taḥlīl): same as baseMaqamIdName (e.g., \"maqam_nahawand\")\nTransposed forms (taṣwīr): includes suffix (e.g., \"maqam_nahawand_al-kurdan\")\n",
            "example": "maqam_rast"
          },
          "maqamDisplayName": {
            "type": "string",
            "description": "Human-readable name (may include transposition info)",
            "example": "Maqam Rast"
          },
          "maqamDisplayNameAr": {
            "type": "string",
            "description": "Arabic display name (only when includeArabic=true)",
            "example": "مقام راست"
          },
          "tonicId": {
            "type": "string",
            "description": "URL-safe tonic identifier",
            "example": "rast"
          },
          "tonicDisplay": {
            "type": "string",
            "description": "Display name for the tonic note",
            "example": "rāst"
          },
          "tonicDisplayAr": {
            "type": "string",
            "description": "Arabic tonic name (only when includeArabic=true)",
            "example": "راست"
          },
          "isTransposition": {
            "type": "boolean",
            "description": "Whether this is a transposition (taṣwīr) or original form (taḥlīl)",
            "example": false
          }
        }
      },
      "ModulationStep": {
        "type": "object",
        "description": "A single step/edge in a modulation route",
        "required": [
          "from",
          "to",
          "modulationDegree",
          "modulationCategory"
        ],
        "properties": {
          "from": {
            "$ref": "#/components/schemas/MaqamNode"
          },
          "to": {
            "$ref": "#/components/schemas/MaqamNode"
          },
          "modulationDegree": {
            "type": "string",
            "description": "Scale degree where modulation occurs",
            "enum": [
              "I",
              "III",
              "IV",
              "V",
              "VI"
            ],
            "example": "III"
          },
          "modulationCategory": {
            "type": "string",
            "description": "Specific modulation category from al-Shawwā's rules",
            "enum": [
              "firstDegree",
              "thirdDegree",
              "altThirdDegree",
              "fourthDegree",
              "fifthDegree",
              "sixthDegreeAsc",
              "sixthDegreeDesc",
              "sixthDegreeIfNoThird"
            ],
            "example": "thirdDegree"
          }
        }
      },
      "ModulationRoute": {
        "type": "object",
        "description": "A complete route from source to target maqam",
        "required": [
          "hops",
          "path"
        ],
        "properties": {
          "hops": {
            "type": "integer",
            "description": "Number of modulation steps",
            "example": 2
          },
          "path": {
            "type": "array",
            "description": "Ordered sequence of modulation steps",
            "items": {
              "$ref": "#/components/schemas/ModulationStep"
            }
          }
        }
      },
      "ModulationJourney": {
        "type": "object",
        "description": "A complete journey including optional return path",
        "required": [
          "totalHops",
          "outboundRoute"
        ],
        "properties": {
          "totalHops": {
            "type": "integer",
            "description": "Total hops for the complete journey (outbound + return if applicable)",
            "example": 4
          },
          "outboundRoute": {
            "$ref": "#/components/schemas/ModulationRoute"
          },
          "returnRoute": {
            "$ref": "#/components/schemas/ModulationRoute",
            "description": "Present when returnToStart=true"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message",
            "example": "Failed to retrieve maqāmāt"
          },
          "message": {
            "type": "string",
            "description": "Additional detailed message explaining the error (not always present)",
            "example": "An unexpected error occurred while processing the request"
          },
          "details": {
            "type": "string",
            "description": "Additional error details (for some error types, not always present)",
            "example": "Database connection failed"
          },
          "hint": {
            "type": "string",
            "description": "Helpful hint for resolving the error (not always present)",
            "example": "Please try again later or contact support"
          },
          "availabilityUrl": {
            "type": "string",
            "description": "URL to check availability (only for missing parameter errors, not always present)",
            "example": "/api/maqamat/{id}/availability"
          },
          "validOptions": {
            "type": "array",
            "description": "List of valid values (only for invalid parameter errors, not always present). These are display values (with diacritics) as returned by the tuning system.",
            "items": {
              "type": "string"
            },
            "example": [
              "ʿushayrān",
              "yegāh"
            ]
          }
        }
      }
    },
    "responses": {
      "ServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Failed to retrieve maqāmāt"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authenticated requests (if implemented in future)"
      }
    }
  },
  "security": []
}