openapi: 3.1.0
info:
  title: API des awrad de la Tidjaniya
  version: "1.0.0"
  summary: Les trois oraisons de la voie tijane en JSON statique versionne.
  description: |
    API statique : un arbre de fichiers JSON pre-rendus, servi par GitLab
    Pages. Il n'y a pas de serveur, pas d'authentification, pas de parametre
    de requete. Toutes les reponses portent la meme enveloppe que les autres
    API Nexus.

    Trois pratiques sont publiees : le Wird Lazim, la Wazifa et le
    Hadaratoul Jouma. Chaque forme est **autonome** : une fois telechargee,
    options et conditions comprises, elle se lit jusqu'au bout sans reseau.

    Trois regles que le consommateur doit comprendre avant de commencer une
    seance, et qu'il lit dans `requiredCapabilities` :

    * `choice` — des alternatives mutuellement exclusives, dont exactement
      une est retenue (Jawharat al-Kamal ou son substitut ; la modalite du
      dhikr du vendredi).
    * `until-event` — une recitation sans cible chiffree, close par le
      coucher du soleil. Elle ne porte pas de champ `times`, et le
      consommateur ne doit pas en fabriquer un.
    * `session-contexts` — une forme recitee dans plusieurs contextes
      (matin, soir) qui partagent les memes donnees de recitation.

    Un lecteur plus ancien lit `requiredCapabilities` dans le catalogue et
    dans la forme, et refuse une forme qu'il ne sait pas mener **avant** de
    commencer, jamais au milieu.
  license:
    name: MIT (outillage et compilation) ; texte des awrad dans le domaine public
    identifier: MIT
servers:
  - url: https://nexus-tijaniyya-awrad-api-4401f3.gitlab.io
    description: URL Pages du projet (sous-chemin de projet) — en service
  - url: https://awrad.nexusprogramming.dev
    description: Domaine dedie — prevu, pas encore en service (DNS a creer)
tags:
  - name: catalogue
  - name: formes
  - name: passages
  - name: references
paths:
  /v1/index.json:
    get:
      tags: [catalogue]
      summary: Le catalogue
      description: |
        Point d'entree. Donne la revision de contenu, les capacites requises
        et, pour chaque forme, un chemin **relatif** a resoudre contre l'URL
        de ce document. Ne jamais assembler un chemin a partir d'un
        identifiant : l'API reste libre de ranger ses fichiers autrement.
      responses:
        "200":
          description: Le catalogue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogueEnvelope"
  /v1/forms/{form}.json:
    get:
      tags: [formes]
      summary: Une pratique complete, autonome
      parameters:
        - name: form
          in: path
          required: true
          schema:
            type: string
            enum: [lazim, wazifa, hadaratoul-jouma]
      responses:
        "200":
          description: La forme, texte resolu, options comprises
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FormEnvelope"
        "404":
          description: Forme inconnue
  /v1/passages/index.json:
    get:
      tags: [passages]
      summary: Le catalogue des passages partages
      description: |
        Les prieres composantes — Salat al-Fatih, Jawharat al-Kamal et les
        autres — exposees individuellement, pour un lecteur qui veut les
        consulter hors d'une seance.
      responses:
        "200":
          description: La liste des passages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PassageIndexEnvelope"
  /v1/passages/{passageId}.json:
    get:
      tags: [passages]
      summary: Un passage isole
      parameters:
        - name: passageId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
          examples:
            salat:
              value: salat-al-fatih
            jawhara:
              value: jawharat-al-kamal
      responses:
        "200":
          description: Le passage, avec ses variantes d'edition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PassageEnvelope"
        "404":
          description: Passage inconnu
  /v1/guide.json:
    get:
      tags: [references]
      summary: Le materiel introductif
      responses:
        "200":
          description: Le guide
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Envelope"
  /v1/sources.json:
    get:
      tags: [references]
      summary: Les editions, leurs divergences et ce qui reste non resolu
      responses:
        "200":
          description: Le registre des sources
          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: {type: object}
    SourceRef:
      type: object
      description: |
        Un endroit precis dans une edition. Une edition imprimee porte
        `page` ; une edition en ligne porte `section`. L'un des deux est
        toujours present, jamais forcement les deux.
      required: [edition]
      properties:
        edition: {type: string}
        page: {type: integer, minimum: 1}
        section: {type: string}
      anyOf:
        - required: [page]
        - required: [section]
    Repetition:
      oneOf:
        - $ref: "#/components/schemas/CountedRepetition"
        - $ref: "#/components/schemas/UntilEventRepetition"
    CountedRepetition:
      type: object
      required: [times, printed]
      properties:
        times: {type: integer, minimum: 1}
        printed:
          type: boolean
          description: |
            Vrai si la source imprime le nombre. Faux pour un passage non
            numerote, recite une fois. La distinction est conservee parce
            qu'un nombre imprime et un nombre deduit ne se valent pas.
        printedAs: {type: string}
        note: {type: string}
    UntilEventRepetition:
      type: object
      required: [mode, event, printed]
      description: |
        Recitation poursuivie jusqu'a un evenement. **Pas de champ `times`** :
        la source n'en donne pas, et en fabriquer un inventerait un compte a
        rebours qui n'existe pas.
      properties:
        mode: {type: string, const: untilEvent}
        event: {type: string, enum: [sunset]}
        eventFr: {type: string}
        eventAr: {type: string}
        printed: {type: boolean}
        printedAs: {type: string}
        note: {type: string}
    Content:
      type: object
      required: [ar, transliterations, translations]
      properties:
        ar:
          type: string
          description: Le texte de recitation, en ecriture arabe.
        transliterations:
          type: array
          description: |
            Transcriptions latines de l'arabe, `language: ar-Latn`. Une
            transcription rend les sons, pas le sens : elle n'est jamais
            comptee comme une traduction.
          items:
            type: object
            required: [language, text, source, status]
            properties:
              language: {type: string, const: ar-Latn}
              script: {type: string, const: Latn}
              convention: {type: string}
              text: {type: string}
              source: {$ref: "#/components/schemas/SourceRef"}
              status: {type: string, enum: [published, editorial, human-reviewed]}
        translations:
          type: array
          description: |
            Traductions du sens, une par langue, triees par code de langue.
            Une langue absente est absente : aucun champ n'est comble par
            une autre langue.
          items:
            type: object
            required: [language, text, source, status]
            properties:
              language: {type: string, pattern: "^[a-z]{2}$"}
              text: {type: string}
              source: {$ref: "#/components/schemas/SourceRef"}
              status:
                type: string
                enum: [published, editorial, human-reviewed]
                description: |
                  `published` : traduction deja publiee par son editeur.
                  `editorial` : rendu propre a ce depot, non revu.
                  `human-reviewed` : rendu relu par un humain competent.
              translator: {type: string}
              note: {type: string}
              translatesVariant:
                type: string
                description: |
                  Presente quand la traduction traduit un texte arabe qui
                  differe de celui publie ici. Nomme l'edition de ce texte.
    PassageStep:
      type: object
      required: [id, type, passage, kind, title, content, repetition]
      properties:
        id: {type: string}
        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}
        role: {type: string, enum: [pillar, opening, closing, recommended]}
        emphasis: {type: string, const: core}
        countingUnit:
          type: string
          enum: [utterance, printedFormula]
          description: |
            Ce qu'une pression du compteur enregistre. `printedFormula`
            quand la source imprime une formule dont l'unite reste
            ambigue : `countingNote` l'explique, et le consommateur
            affiche la note plutot que de trancher.
        countingNote: {type: string}
        note: {type: string}
        content: {$ref: "#/components/schemas/Content"}
        repetition: {$ref: "#/components/schemas/Repetition"}
        sources: {type: object}
        availability: {type: object}
    GroupStep:
      type: object
      description: |
        Un bloc repete comme un tout : `(A,B) x 3` vaut `A,B,A,B,A,B` et
        non `A,A,A,B,B,B`. Ce sont deux prieres differentes.
      required: [id, type, repetition, steps]
      properties:
        id: {type: string}
        type: {type: string, const: group}
        repetition: {$ref: "#/components/schemas/CountedRepetition"}
        steps:
          type: array
          items: {$ref: "#/components/schemas/Step"}
    ChoiceStep:
      type: object
      description: |
        Alternatives mutuellement exclusives. Le consommateur en retient
        exactement une, avant le debut de la seance, et enregistre son
        identifiant dans la session.
      required: [id, type, selection, title, options]
      properties:
        id: {type: string}
        type: {type: string, const: choice}
        selection: {type: string, const: exactlyOne}
        decidedBefore: {type: string, enum: [session, step]}
        title: {type: string}
        divergenceNote: {type: string}
        historicalNote: {type: string}
        source: {$ref: "#/components/schemas/SourceRef"}
        options:
          type: array
          minItems: 2
          items:
            type: object
            required: [id, title, order, when, steps]
            properties:
              id: {type: string}
              title: {type: string}
              order: {type: integer}
              when:
                type: string
                description: La condition qui designe cette option.
              audience: {type: string, enum: [individuel, groupe]}
              mixedSequence:
                type: boolean
                description: |
                  Vrai quand l'option enchaine deux formules distinctes
                  dans un ordre qui compte.
              conditions:
                type: array
                items: {type: string}
              conditionsSource: {$ref: "#/components/schemas/SourceRef"}
              steps:
                type: array
                items: {$ref: "#/components/schemas/Step"}
    Step:
      oneOf:
        - $ref: "#/components/schemas/ChoiceStep"
        - $ref: "#/components/schemas/GroupStep"
        - $ref: "#/components/schemas/PassageStep"
    Form:
      type: object
      required:
        [apiVersion, contentRevision, id, title, requiredCapabilities, sections]
      properties:
        apiVersion: {type: string, const: v1}
        contentRevision: {type: string, pattern: "^[0-9a-f]{64}$"}
        id: {type: string}
        title: {type: string}
        titleAr: {type: string}
        titleFr: {type: string}
        aliases:
          type: array
          items: {type: string}
          description: Noms regionaux, pour la recherche. Jamais une autre pratique.
        textEdition: {type: string}
        requiredCapabilities:
          type: array
          items: {type: string, enum: [choice, until-event, group, session-contexts]}
        contexts:
          type: array
          description: |
            Contextes de seance partageant les memes donnees de recitation.
            Une session sauvegardee doit retenir lequel.
          items: {type: object}
        completeness: {type: object}
        coverage:
          type: object
          description: |
            Nombre de passages **distincts** portant chaque type de contenu.
            Seul le texte embarque est compte : rien de seulement lie.
        executionPaths:
          type: array
          description: |
            Un resume par parcours complet possible. `totalRecitations` vaut
            `null` sur un parcours ouvert.
          items: {type: object}
        choices:
          type: array
          description: Les identifiants de choix et d'option, pour la session.
          items: {type: object}
        sections:
          type: array
          items: {type: object}
    Catalogue:
      type: object
      required: [apiVersion, contentRevision, forms, resources, endpoints]
      properties:
        apiVersion: {type: string, const: v1}
        contentRevision: {type: string, pattern: "^[0-9a-f]{64}$"}
        license: {type: string}
        requiredCapabilities:
          type: array
          items: {type: string}
        capabilityGlossary: {type: object}
        forms:
          type: array
          items:
            type: object
            required: [id, title, path, requiredCapabilities]
            properties:
              id: {type: string}
              title: {type: string}
              path:
                type: string
                description: Relatif a l'URL de ce document.
              requiredCapabilities: {type: array, items: {type: string}}
              hasOpenEndedPath:
                type: boolean
                description: |
                  Vrai si l'un des parcours n'a pas de cible chiffree.
                  Lisible avant tout telechargement.
        resources: {type: object}
        languages: {type: array, items: {type: string}}
        translationStatus: {type: object}
        endpoints: {type: array, items: {type: string}}
    Passage:
      type: object
      required: [apiVersion, contentRevision, id, kind, title, content]
      properties:
        apiVersion: {type: string, const: v1}
        contentRevision: {type: string}
        id: {type: string}
        kind: {type: string, enum: [quran, dhikr, dua, salat]}
        title: {type: string}
        content: {$ref: "#/components/schemas/Content"}
        vocalised:
          type: boolean
          description: |
            Vrai si le texte porte les harakat. Aucune voyelle n'est jamais
            ajoutee a une source qui n'en porte pas.
        usedBy:
          type: array
          items: {type: string}
          description: Les formes qui recitent ce passage.
        arByEdition:
          type: object
          description: Le meme passage tel que l'imprime une autre edition.
        editionVariants: {type: array, items: {type: object}}
        textNotes: {type: string}
    CatalogueEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            data: {$ref: "#/components/schemas/Catalogue"}
    FormEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            data: {$ref: "#/components/schemas/Form"}
    PassageEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            data: {$ref: "#/components/schemas/Passage"}
    PassageIndexEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            data:
              type: object
              properties:
                passages:
                  type: array
                  items:
                    type: object
                    properties:
                      id: {type: string}
                      path: {type: string}
                      languages: {type: array, items: {type: string}}
                      usedBy: {type: array, items: {type: string}}
