openapi: 3.1.0
info:
  title: Wird Ma'houz API
  version: "1.0.0"
  summary: >-
    API statique pour le Wird Ma'houz mouride : les deux formes, le texte arabe
    vocalise, la transcription latine, les nombres de repetitions et les sources.
  description: |
    Un arbre de fichiers JSON statiques publies sur GitLab Pages. Il n'y a pas
    de serveur, pas de cle, pas d'authentification.

    Toutes les reponses partagent l'enveloppe `{code, status, data}`. Une
    ressource absente est un 404 HTTP de Pages, pas une enveloppe porteuse d'un
    code d'erreur.

    Les chemins de forme donnes par le catalogue sont **relatifs** : un client
    les resout contre l'URL de base plutot que de reconstruire `forms/{id}.json`.
  license:
    name: MIT (outillage et compilation) ; wird dans le domaine public
    url: https://gitlab.com/nexus-programming/nexus-wird-mahouz-api/-/blob/main/LICENSE
  contact:
    name: Issues
    url: https://gitlab.com/nexus-programming/nexus-wird-mahouz-api/-/issues

servers:
  - url: https://wird.nexusprogramming.dev
    description: Domaine dedie (canonique)
  - url: https://nexus-wird-mahouz-api-51ac4a.gitlab.io
    description: GitLab Pages, repond 200 aussi
  - url: https://cdn.statically.io/gl/nexus-programming/nexus-wird-mahouz-api@v1.0.0
    description: CDN Statically, epingle sur un tag

paths:
  /v1/index.json:
    get:
      operationId: getCatalogue
      summary: Le catalogue
      description: >-
        Version d'API, revision de contenu, les deux formes avec leurs alias,
        langues, ecritures, completude et chemin relatif, plus l'etat des
        traductions.
      responses:
        "200":
          description: Le catalogue
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/Catalogue"

  /v1/forms/{form}.json:
    get:
      operationId: getForm
      summary: Une forme, complete et autonome
      description: >-
        Tout ce qu'il faut pour reciter la forme d'un bout a l'autre hors
        ligne : sections ordonnees, etapes ordonnees, texte arabe, transcription
        quand elle existe, nombres de repetitions et references de source.
      parameters:
        - name: form
          in: path
          required: true
          schema:
            type: string
            enum: [khafif, kamil]
          description: >-
            `khafif` (forme allegee, 21 etapes de recitation) ou `kamil` (forme
            complete, 27 etapes ; imprimee « al akmal » dans l'edition de 2013).
      responses:
        "200":
          description: La forme
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/Form"
        "404":
          description: Forme inconnue

  /v1/sources.json:
    get:
      operationId: getSources
      summary: Editions, credits et collation
      responses:
        "200":
          description: Les sources
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Envelope"

  /v1/guide.json:
    get:
      operationId: getGuide
      summary: Materiel introductif commun aux deux formes
      description: >-
        Les consignes necessaires pendant la recitation ne sont pas ici : elles
        voyagent aussi dans la charge utile de chaque forme.
      responses:
        "200":
          description: Le guide
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Envelope"

components:
  schemas:
    Envelope:
      type: object
      required: [code, status, data]
      properties:
        code:
          type: integer
          const: 200
        status:
          type: string
          const: OK
        data:
          description: La charge utile ; c'est tout ce qu'un client deballe.

    Catalogue:
      type: object
      required: [apiVersion, contentRevision, forms, resources]
      properties:
        apiVersion:
          type: string
          const: v1
        contentRevision:
          type: string
          description: >-
            Empreinte du contenu. Change des que le contenu change ; c'est le
            signal de rafraichissement d'un cache client.
        license:
          type: string
        forms:
          type: array
          items:
            $ref: "#/components/schemas/CatalogueForm"
        resources:
          type: object
          additionalProperties:
            type: string
          description: Chemins relatifs des ressources annexes.
        languages:
          type: array
          items:
            type: string
        scripts:
          type: array
          items:
            type: string
        translationStatus:
          type: object
        endpoints:
          type: array
          items:
            type: string

    CatalogueForm:
      type: object
      required: [id, title, aliases, languages, completeness, path]
      properties:
        id:
          type: string
          examples: [khafif, kamil]
        title:
          type: string
        titleAr:
          type: string
        titleFr:
          type: string
        aliases:
          type: array
          items:
            type: string
          description: >-
            Graphies rencontrees dans les editions. « al akmal » est un alias de
            `kamil` : c'est le titre que lui donne l'edition de 2013.
        order:
          type: integer
        languages:
          type: array
          items:
            type: string
        scripts:
          type: array
          items:
            type: string
        completeness:
          $ref: "#/components/schemas/Completeness"
        counts:
          type: object
        totalRecitations:
          type: integer
        path:
          type: string
          description: Chemin **relatif** vers la forme, a resoudre contre l'URL de base.
          examples: ["forms/khafif.json"]

    Completeness:
      type: object
      required: [status, ar, transliteration, translation]
      properties:
        status:
          type: string
          enum: [complete, incomplete]
          description: >-
            `incomplete` des qu'un passage requis ou un nombre de repetitions
            reste non resolu.
        ar:
          type: string
          enum: [complete, partielle, indisponible]
        transliteration:
          type: string
          enum: [complete, partielle, indisponible]
        translation:
          type: string
          enum: [complete, partielle, indisponible]
        note:
          type: string

    Form:
      type: object
      required: [id, title, aliases, contentRevision, sections]
      properties:
        id:
          type: string
        title:
          type: string
        titleAr:
          type: string
        titleFr:
          type: string
        aliases:
          type: array
          items:
            type: string
        contentRevision:
          type: string
        textEdition:
          type: string
        isnad:
          type: string
        textualBasis:
          type: string
        headingNote:
          type: string
        orderVerifiedAgainst:
          type: object
        completeness:
          $ref: "#/components/schemas/Completeness"
        counts:
          type: object
        totalRecitations:
          type: integer
          description: Somme des repetitions de toutes les etapes.
        sections:
          type: array
          description: Tableau ordonne — l'ordre de lecture est l'ordre du tableau.
          items:
            $ref: "#/components/schemas/Section"

    Section:
      type: object
      required: [id, title, steps]
      properties:
        id:
          type: string
          examples: [ouverture, recitation, cloture]
        title:
          type: string
        titleAr:
          type: string
        titleFr:
          type: string
        instruction:
          $ref: "#/components/schemas/Instruction"
        steps:
          type: array
          items:
            $ref: "#/components/schemas/Step"

    Instruction:
      type: object
      description: >-
        Consigne imprimee par la source et necessaire pendant la recitation.
        Elle voyage dans la charge utile de la forme, pas seulement dans le guide.
      required: [source]
      properties:
        ar:
          type: string
        fr:
          type: string
        wo:
          type: string
        source:
          $ref: "#/components/schemas/SourceRef"

    Step:
      oneOf:
        - $ref: "#/components/schemas/PassageStep"
        - $ref: "#/components/schemas/GroupStep"
      discriminator:
        propertyName: type
        mapping:
          passage: "#/components/schemas/PassageStep"
          group: "#/components/schemas/GroupStep"

    PassageStep:
      type: object
      required: [id, type, kind, title, content, repetition, availability, sources]
      properties:
        id:
          type: string
          description: >-
            Identifiant **stable**, independant de la position dans le tableau,
            du numero de page et des titres traduits. C'est lui qu'un client
            enregistre pour reprendre une lecture.
          examples: [salat-al-fatih]
        type:
          type: string
          const: passage
        passage:
          type: string
        kind:
          type: string
          enum: [quran, dhikr, dua, salat]
        title:
          type: string
        titleAr:
          type: string
        quranRef:
          type: string
          description: >-
            Sourate:verset, a titre de provenance. Le texte servi reste celui de
            l'edition citee, transcrit fidelement — il n'a pas ete normalise sur
            le rasm uthmani.
          examples: ["2:255"]
        emphasis:
          type: string
          enum: [core]
        brackets:
          type: array
          description: >-
            Crochets droits de l'edition source : ajouts attestes dans d'autres
            copies manuscrites. Ce n'est pas une convention de cette API.
          items:
            type: object
        note:
          type: string
        content:
          $ref: "#/components/schemas/Content"
        repetition:
          $ref: "#/components/schemas/Repetition"
        availability:
          type: object
          description: Ce qui existe reellement pour cette etape.
          properties:
            ar:
              type: boolean
            transliteration:
              type: boolean
            translation:
              type: boolean
        sources:
          type: object
          description: >-
            Le texte arabe, la transcription et la traduction peuvent venir
            d'editions differentes ; chacun porte donc sa propre provenance.
          properties:
            ar:
              type: array
              items:
                $ref: "#/components/schemas/SourceRef"
            transliteration:
              $ref: "#/components/schemas/SourceRef"
            translations:
              type: object

    GroupStep:
      type: object
      description: >-
        Un groupe est repete **en bloc** : `times: 3` sur un groupe (A, B) se
        recite (A, B) x 3, et non A x 3 puis B x 3 — ce qui changerait l'ordre
        de lecture.
      required: [id, type, repetition, steps]
      properties:
        id:
          type: string
        type:
          type: string
          const: group
        repetition:
          $ref: "#/components/schemas/Repetition"
        note:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/Step"

    Content:
      type: object
      required: [ar, transliterations, translations]
      properties:
        ar:
          type: string
          description: Arabe vocalise, a afficher de droite a gauche.
        transliterations:
          type: array
          description: Vide quand l'edition source n'en porte pas. Jamais invente.
          items:
            type: object
            properties:
              language:
                type: string
              script:
                type: string
                const: Latn
              convention:
                type: string
              text:
                type: string
              reflowed:
                type: boolean
                description: >-
                  L'ordre des mots imprime a ete retabli, la mise en page de la
                  source ayant deplace un fragment de ligne.
              misplacedInSource:
                type: boolean
                description: >-
                  La ligne est imprimee sous un autre passage dans la source ;
                  voir `note`.
              source:
                $ref: "#/components/schemas/SourceRef"
        translations:
          type: array
          description: >-
            Vide aujourd'hui pour toutes les etapes : aucune edition consultee
            ne traduit le texte de recitation.
          items:
            type: object

    Repetition:
      type: object
      required: [times, printed]
      properties:
        times:
          type: integer
          minimum: 1
        printed:
          type: boolean
          description: >-
            `true` si la source imprime explicitement un nombre ; `false` pour un
            passage non marque, qui se recite une fois. Un client n'affiche un
            compteur que si `printed` est vrai.
        printedAs:
          type: string
          description: Le nombre tel qu'il est imprime.
          examples: ["3 مرات"]

    SourceRef:
      type: object
      required: [edition, page]
      properties:
        edition:
          type: string
          examples: [xassaid-kamil-2023]
        page:
          type: integer
          minimum: 1
