Liturgie

Ce domaine est vaste et complexe. Ces notes doivent rester concises pour être utiles.

Le domaine des données liturgiques et sa représentation par l’API. Il s’agit d’un modèle de domaine, pas d’un état des réalisations. Les Notes signalent les choix ou limites délibérés des structures ; les Limites indiquent les éléments non servis.

Ce que fournit l’API

Pour un (calendar, region, date), elle résout et renvoie :

1. Contexte du jour : date civile et jour de semaine, temps liturgique et semaine, cycles de l’année liturgique (lectionnaire de la forme ordinaire A/B/C, jours de semaine I/II, semaine du psautier), état d’obligation.
2. Célébration : identité du jour, nom multilingue, rang, couleur, identifiant textuel du saint, catégories des Communs et appartenance à une octave.
3. Commémoraisons : autres saints inclus par des prières ajoutées.
4. Fêtes du jour : chaque saint lié à cette date, classé par résultat (célébré, commémoré, omis ou arrivé), afin de répondre directement aux questions sur les fêtes (§6).
5. Messe(s) : propres (introït à postcommunion) et lectures (référence et texte), plusieurs lorsqu’un jour en comporte plusieurs (Noël, vigiles, Requiem).
6. Office : les huit heures assemblées (psaumes, antiennes, hymne, chapitre, cantique, collecte), premières et secondes vêpres distinguées.
7. Résolution facultative : raison du choix de cet office, offices commémorés, omis, transférés ou non célébrés.
8. Saints : accessibles par rite (/{calendar}/saints/{id}).

Tout texte lisible est une correspondance { la, en, … }, avec le latin comme base. La liturgie est une résolution : le temporal (temps, depuis Pâques) et le sanctoral (fêtes fixes) proposent chacun un office ; la préséance, avec occurrence dans la journée et concurrence à ses limites, choisit celui retenu et le sort des autres. L’office retenu fournit messe et Office, assemblés selon Propre → Commun → Psautier.

Points de terminaison

Règle d’emplacement. Les ressources communes aux rites sont au niveau supérieur (/calendars, /saints, /regions) ; celles d’un rite sont sous /calendars/{cal}. Un jour renvoie un résumé léger. Les couches lourdes sont incluses par ?include= pour les lots ou accessibles comme sous-ressources pour les liens directs ; les deux existent (voir Inclusions).

Inclusions. ?include=masses,office,resolution,martyrology intègre ces couches lourdes au jour ou à chaque jour d’une plage ou année. Une vue des lectures du mois exige ainsi un appel. Les URL de sous-ressources (…/masses, …/office/{hour}, …/resolution) restent disponibles pour les liens directs. Sans include, un jour comprend uniquement le résumé et links.

Les collections (/days?from..to, /years/{label} et les deux recherches /saints) renvoient une enveloppe, jamais un tableau nu, pour montrer requête répétée, totaux, pagination et plafonds appliqués :

{ "results": [ … ], "query": { … echoed, incl. region }, "page": { "total": 342, "next": "…cursor…" },
  "warnings": [ "span capped to 90 days" ] }   // warnings only when something was clamped

Les tableaux dans une ressource (saints.*, readings) restent des sous-champs bornés, sans enveloppe de collection.

Identifiants et négociation.

• Dates : un jour précis est au format ISO complet YYYY-MM-DD ; une fête fixe récurrente utilise MM-DD ; une fête mobile un objet anchor (§2). L’année liturgique possède sa propre identité : {label} est la plage canonique YYYY-YYYY d’un Avent à l’autre, par exemple 2025-2026, évitant l’ambiguïté de l’année de début ou de fin. Un YYYY seul, désignant l’année commençant à l’Avent de YYYY, ou toute date contenue, donne une redirection 301 vers cette plage : une année, une URL.
• region est un affinement facultatif de requête. Absent ou inconnu, il revient à general, l’édition typique, sans erreur, avec region_default_applied. Le segment structurel {cal}, identifiant cal invalide, renvoie 404.
• Les identifiants du chemin ignorent la casse. {cal} (ordinary/traditional/dominican, sans alias), {hour} et {mass} sont résolus quelle que soit la casse (Traditional, Vespers, MIDNIGHT fonctionnent). Un identifiant réellement inconnu renvoie 404. Cette tolérance aide l’appelant.
• La langue utilise Accept-Language, sans chemin ni paramètre. Le latin reste la base ; la sélection est additive et 406 n’est jamais renvoyé. Les réponses portent Vary: Accept-Language.
• La traduction est un second axe distinct de la langue. Une langue peut avoir plusieurs éditions bibliques (anglais : douay, cpdv ; latin : vulgate, clémentine, avec Nova Vulgata prévue). Le paramètre facultatif translations les choisit : editions= est le nom canonique correspondant à la réponse, translations= un alias accepté. La liste séparée par des virgules (editions=cpdv,vulgate) admet au plus une édition par langue et concerne uniquement le text des lectures. Références et textes non bibliques en sont indépendants. Une valeur absente ou inconnue revient à l’édition par défaut de la langue, sans erreur, signalée par editions et un élément warnings dans les collections. Chaque text de lecture indique son edition, sans ambiguïté. /liturgy/v1/translations liste les éditions disponibles. Le choix entre dans Vary et l’ETag ci-dessous. Un paramètre est utilisé parce que l’étiquette HTTP choisit une langue, pas une édition éditoriale ; la surcharge en-x-cpdv n’est pas standard et ne peut pas être correctement mise en cache par les CDN sensibles aux langues.
• Les identifiants textuels des saints relèvent de deux espaces : id du rite et person canonique. Les liens croisés sont donc obligatoires : l’entrée de rite porte person vers le haut, et calendars{} de la personne porte ref vers le bas. Aucun identifiant ne conduit à une impasse.

Cache. Une réponse est une fonction pure de (cal, date, region, Accept-Language, translations, data-version). L’ETag incorpore les six ; un CDN basé sur chemin et Vary ne peut donc pas servir une mauvaise variante. Une correction de données ou nouvelle table régionale incrémente data-version et change tous les ETag concernés. Cela permet l’invalidation des jours passés, gardés longtemps en cache mais jamais immutable. If-None-Match renvoie 304.

Versions et cycle de vie. /liturgy/v1 est additif dans la version majeure : des champs peuvent être ajoutés, jamais retirés ni changer de type. Les éditions et régions arrivent comme données (§2). Une rupture est publiée sous /liturgy/v2 ; une date de retrait de l’ancienne version est alors annoncée par les en-têtes Deprecation et Sunset, avec au moins douze mois de préavis. Les champs obsolètes portent un lien Deprecation dans la documentation. Aucun élément de v1 ne change silencieusement.

Les erreurs utilisent application/problem+json (RFC 9457), avec une URI machine type stable, title, status, detail et instance :

• 400 : entrée mal formée, telle qu’une date non canonique YYYY-MM-DD sans zéros ou une valeur include interdite.
• 404 : {cal}, {person}, {id} inconnu ou {hour}/{mass} non exposé par ce jour.
• 405 : verbe autre que GET sur un chemin valide ; l’API est en lecture seule et renvoie Allow: GET.
• 406 : jamais renvoyé, toute demande Accept-Language étant satisfaite par la base latine.
• 422 : requête bien formée hors de la période prise en charge par l’édition.
• 429 : limitation de requêtes, avec Retry-After.
• Une region invalide, édition translations inconnue ou plage from/to trop grande ne provoque jamais d’erreur : repli ou plafonnement, valeur appliquée répétée (region_default_applied/editions) et élément warnings dans les collections.

Conventions.

• Type de média application/json. Le contrat machine canonique est le document OpenAPI 3.1 publié (/liturgy/v1/openapi.json), dont les clients sont générés et qui fait autorité pour toutes les structures esquissées ici.
• Lecture seule et idempotence. Tous les points utilisent GET : sûrs, idempotents et pouvant être mis en cache. Sans écriture, aucune clé d’idempotence n’est nécessaire.
• Authentification et limites. Les requêtes portent une clé API (Authorization: Bearer gianna_…) créée dans l’application par tout compte (POST /api/keys, affichée une fois ; gestion et révocation par GET/DELETE /api/keys). Une session de navigateur connectée convient aussi dans l’application. Ces données sont gratuites et nécessitent un compte. Sans authentification : 401 avec WWW-Authenticate: Bearer. Une session de visiteur anonyme : 403. L’index, openapi.json et les flux feasts.ics sont publics sans clé. Les fenêtres fixes par foyer sont imposées avec 429, Retry-After et RateLimit-Limit sur le 429 ; la limitation IP initiale appartient au proxy inverse. L’authentification et les formules ne modifient pas la représentation ni la clé de cache.
• En-têtes de cache. Chaque réponse a un ETag, un Cache-Control: public, max-age=… borné et stale-while-revalidate. Les dates passées ont une longue durée puisque la réponse rubricale est stable, mais pas immutable : une correction ou nouvelle table region peut modifier une résolution historique. L’ETag, basé sur version des données, région et langues, permet l’invalidation ; les clients revalident par If-None-Match. Les réponses sont public parce qu’elles ne varient pas selon l’appelant ; l’accès est toutefois contrôlé et le cache périphérique de l’opérateur doit vérifier la clé avant de servir le cache. Ne placez pas un cache partagé anonyme devant /liturgy/v1.
• Aujourd’hui. Aucune ressource serveur « aujourd’hui » : le jour liturgique suit la date civile de l’appelant, que le serveur UTC ne doit pas décider. Le client détermine sa date locale et la demande explicitement (…/days/2026-06-09). Accept-Language et region n’impliquent aucune date.
• Protection du coût de ?include. Pour les couches lourdes office et masses, include est refusé avec 400 sur les collections de plusieurs jours au-delà d’une petite durée, par exemple 31 jours. Une année ne peut donc pas demander une réponse démesurée ; utilisez les sous-ressources journalières. resolution, léger, reste toujours inclusible.

1. Calendriers et rites

Chaque système est autonome : sanctoral, préséance, propres et édition. Une date est résolue indépendamment dans chaque rite ; la préséance relève du rite (§4).

Chaque rite a un identifiant stable, ordinary, traditional ou dominican, sans alias, et indique s’il expose un Office.

Note : une nomenclature dans toute l’application. Ces mots sont les noms dans tout le produit : préférence de calendrier enregistrée du foyer, /api/prefs, outil liturgique de l’agent et textes de l’interface. Les anciens identifiants et alias (roman-ordinary, roman-1962, general, of, tlm, op) ont été retirés lors d’un changement avant l’existence de clients externes : ils renvoient 404, sont refusés par les préférences et la migration 0029 a réécrit les lignes enregistrées. Les synonymes humains, « TLM », « messe latine », « forme extraordinaire », « Novus Ordo », sont compris par le modèle et associés au nom canonique ; les analyseurs acceptent uniquement les trois, sans distinction de casse.

2. Entrées de résolution : rite, année, région

Temporal : mobile, ancré sur Pâques, d’où Septuagésime, mercredi des Cendres, Ascension, Pentecôte et comptes des dimanches ; l’Avent ancre l’autre extrémité. Il dépend de l’année.

Note : Pâques est calculé par le comput grégorien occidental. Chaque date mobile en dépend ; il est donc fixé à un algorithme nommé et à une table de régression de dates connues. Le comput oriental julien et les calculs historiques divergents ne sont pas pris en charge.

Le sanctoral comprend trois types :

• Fixe : mois et jour indépendants de l’année, comme Noël le 25 décembre. La majorité.
• Mobile : règle d’ancrage au temporal, comme Sainte Famille le dimanche de l’octave de Noël, sinon le 30 décembre, ou Sacré-Cœur le vendredi après l’octave de la Fête-Dieu. Porte anchor.
• Mobile et différent selon le rite : règle propre à chaque rite, comme le Christ-Roi, dernier dimanche avant l’Avent dans la forme ordinaire, dernier dimanche d’octobre en 1962. L’ancrage appartient au couple (feast, rite).

{ "id": "sacred-heart", "kind": "moveable",
  "anchor": { "base": "corpus-christi-octave", "offset": "friday-after" } }
// base: a named temporale point (easter | pentecost | corpus-christi | advent | epiphany |
//   christmas | <-octave variants>);  offset: nth-weekday-after/before | sunday-within | n-days

Note : couches de différences internes, résultats fusionnés exposés. Une version est une table de base et des couches de réforme (1568 à 1960). C’est une technique de construction, pas un axe exposé. Aucun sélecteur d’année des rubriques, donc aucune demande de « 1939 » ; le choix d’édition reste futur (Limites).

Région : trois effets rubricaux, dont deux modélisés : fêtes transférées au dimanche selon la conférence (Épiphanie, Ascension, Fête-Dieu) et fêtes de précepte (§3a). Elle apporte aussi des fêtes propres, notamment patronales, non modélisées (Limites).

Note : la région modélise une partie du rôle réel d’une conférence. Les fêtes propres affectent la préséance, puisqu’une solennité patronale change le jour ; seuls transfert et précepte sont modélisés. Le défaut general est l’édition typique : Ascension, Épiphanie et Fête-Dieu restent leur jour de semaine même si beaucoup de pays les célèbrent le dimanche. La réponse par défaut correspond donc à l’édition typique. Les tables des conférences s’ajoutent comme données au fil du temps.

Année liturgique : commence au premier dimanche de l’Avent ; une année civile en traverse deux. Les cycles de la forme ordinaire en dépendent :

"liturgical_year": {
  "starts": "2025-11-30",
  "sunday_cycle":  "C",   // OF A|B|C — rolls over at ADVENT;  null for 1962
  "weekday_cycle": "II",  // OF I|II  — rolls over at 1 JAN;   null for 1962
  "psalter_week":  2      // OF 1–4   — null when overridden
}

Note : les deux cycles changent à des dates différentes. Le cycle dominical change à l’Avent ; celui des jours de semaine, I pour les années civiles impaires, au 1er janvier. Un seul starts ne suffit pas à déduire les deux ; ils sont fournis résolus. Les cycles valent null en 1962, annuel. psalter_week vaut null dans bien d’autres cas : solennités et fêtes prennent la semaine I ; octaves, derniers jours de l’Avent et Semaine sainte remplacent le psautier. C’est un indice pour les jours ordinaires, pas un simple entier de 1 à 4.

3. Le jour liturgique

Le point journalier renvoie le résumé, noyau léger et liens. Office, propres complets et résolution sont des demandes distinctes selon le tableau précédent. Le résumé :

{
  "calendar": "traditional", "region": "general",
  "region_default_applied": true,  // true only when the caller named no region (§2)
  "editions": { "la": "vulgate", "en": "douay" },  // scripture edition per language, always present (§10)
  "date": "2026-01-28",       // CIVIL date (see note)
  "weekday": "wednesday",     // CIVIL weekday of the civil date
  "liturgical_year": { /* §2 */ },
  "season":     { "id": "epiphany", "arc": "after-epiphany", "week": 3 },  // §5
  "obligation": { /* §3a */ },
  "celebration":    { /* below — the headline, singular */ },
  "saints": {                  // §6 — THE field for "whose feast day is it?"
    "celebrated":   [ { "name": {…}, "id": "…", "person": "…", "rank": {…} } ],
    "commemorated": [ /* sanctoral commemorations; never the feria */ ],
    "associated":   [ /* fixed-date saints in this calendar, independent of precedence */ ],
    "remembered":   [ { "name": "Ss. Primus and Felician" }, … ]  // notes via ?include=martyrology
  },
  "masses": [ { "id": "day", "name": {…}, "colour": {…}, "option_type": "prescribed" } ],
  "links": { "office_url": "…", "masses_url": "…", "resolution_url": "…" }
}

Note : saints conserve des registres séparés. celebrated et commemorated sont les résultats de CE calendrier ; une férie n’est pas un saint et n’y figure jamais. associated est l’index des saints à date fixe du calendrier choisi ; la préséance n’efface donc pas l’association à une fête. remembered est le Martyrologe romain, contenant TOUS les saints de la date, souvent 5 à 15, célébrés ou non quelque part. L’édition de 1916 du domaine public est intégrée : les saints canonisés depuis en sont absents mais peuvent figurer dans le calendrier ; ses dates suivent l’ancien calendrier lorsqu’elles diffèrent. Les futurs résultats transferred et omitted arriveront comme clés additives. remembered[].name est uniquement anglais (Limites). Les noms sont toujours présents ; l’éloge note s’inclut par ?include=martyrology, inclusion lourde plafonnée comme masses et office, car 90 jours d’éloges représenteraient la majorité de la réponse. Les réponses sont compressées en gzip si négocié.

Note : le résumé liste des descripteurs de messes. masses[] porte le léger { id, name, colour, option_type }, sans propres, accessibles par masses_url ou ?include=masses. Un simple nombre exigerait un second appel pour les identités des messes. De plus, celebration.colour est la couleur du jour et peut différer des couleurs de chaque messe, comme un Requiem noir un jour blanc (§7). La colour propre à chaque messe fait autorité pour afficher une case du calendrier.

Note : clé de date civile et deux faits distincts du samedi soir. Point ouvert. La date civile reste la clé afin qu’une demande du 2026-06-09 soit sans ambiguïté. Les débordements du soir sont des relations explicites séparées : premières vêpres, où l’Office du lendemain est récité ce soir (liturgical_evening.belongs_to), et messe anticipée, où la messe du samedi soir accomplit le précepte dominical (anticipated_mass). L’Office peut être celui du lendemain tandis que la messe reste celle du jour. La structure exacte reste ouverte.

3a. Obligation : dépend de la région et ne se déduit pas du rang

"obligation": {
  "status": "lapsed",                        // yes | no | lapsed
  "reason": "falls on a Monday in region X", // display
  "reason_code": "lapses-monday"   // null | lapses-saturday | lapses-monday | transferred | not-precept-in-region
}

Note : trois états et identifiant machine. Un booléen ne porte pas la règle de précepte partiel, qui tombe le samedi ou lundi, sans varier chaque année. reason_code accompagne le texte pour le programme. À general, l’édition typique donne le droit universel : tous les dimanches et les dix fêtes du canon 1246 (huit fixes, Ascension et Fête-Dieu mobiles), avec leur nom dans reason. Le précepte ne se déduit pas du rang ; la plupart des solennités n’en ont pas. Les suppressions et transferts régionaux (reason_code, lapsed) arrivent avec les tables de région.

Célébration

{
  "name":  { "la": "S. Petri Nolasci Confessoris", "en": "St. Peter Nolasco, Confessor" },
  "rank":  { "label": "class-3", "precedence": 711, "cycle": "sanctorale" },  // §4
  "colour": { "default": "white", "alternatives": [] },                       // §5
  "id":     "petrus-nolascus",     // RITE-SCOPED slug → /{calendar}/saints/{id}
  "person": "peter-nolasco",       // canonical link UP → /liturgy/v1/saints/{person} (§11) — mandatory
  "titles": ["confessor"],         // category SET → Common(s) (§8)
  "octave": null                   // or { "of", "day" } (§9)
}

Note : identifiant textuel du rite et lien supérieur person. Le même saint peut avoir un rang, nom ou date différent selon le rite. id désigne la célébration de ce rite ; person est le lien obligatoire vers la notice canonique commune (§11), dont calendars{} renvoie vers le bas. Les deux espaces d’identifiants ne se confondent pas puisque chaque identifiant est toujours associé à l’autre.

4. Rang, préséance et résolution

La partie la plus codifiée pose deux questions : occurrence, quand deux offices tombent le même jour, et choix entre célébration, commémoraison, omission ou transfert ; concurrence, quand les secondes vêpres d’un office rencontrent les premières du suivant (§8).

Les degrés diffèrent selon le rite. En 1962 et rite dominicain : quatre classes I à IV, commémoraisons et féries ; classes de fêtes et de jours (dimanche, férie, vigile, jour d’octave) s’entrecroisent. Une férie de première classe précède une fête de première classe ; un dimanche de deuxième classe précède une fête de troisième, qui est commémorée. Dans la forme ordinaire : Solennité > Fête > Mémoire > Mémoire facultative > Jour de semaine, selon la table de 1969.

Note : les dimanches ont plusieurs rangs. En 1962, les dimanches de première classe, d’Avent, Carême et Passion, n’admettent presque rien ; ceux de deuxième classe, verts, peuvent céder à une fête de deuxième classe. La forme ordinaire suit un principe parallèle : dimanches d’Avent, Carême et Pâques devant toutes les fêtes ; dimanches ordinaires cédant aux fêtes du Seigneur. Le rang contient la classe spécifique du dimanche.

"rank": { "label": "class-1", "precedence": 910, "cycle": "temporale" }
// label = native grade; precedence = sortable (higher outranks); cycle = which PROPOSED it

Notes sur rank.

• cycle est le cycle qui propose : dimanche et férie sont temporale même si ce sont des classes de jours ; la distinction est dans label.
• precedence compare dans une seule résolution, pour un rite et un jour. La comparaison entre rites n’a pas de sens (§1).
• precedence trie sans décider. Point ouvert. Certaines règles sont conditionnelles : une fête du Seigneur remplace un dimanche ordinaire, mais pas d’Avent, Carême ou Pâques. Deux entiers ne suffisent pas ; le moteur utilise la table complète, l’entier étant le résultat. Exposer la règle ou seulement son résultat reste ouvert.
• Le jour n’a pas un rang scalaire unique. Messe, heures diurnes et deux vêpres peuvent être résolues vers différents offices, accessibles séparément (§7/§8).

La résolution, facultative, expose la décision :

"resolution": {
  "winner": "sanctorale",
  "displaced": [
    { "name": {…}, "outcome": "commemorated" },
    { "name": {…}, "outcome": "omitted" },
    { "name": {…}, "outcome": "not-observed" },  // dropped for the year
    { "name": {…}, "outcome": "transferred", "chain": ["2026-01-28","2026-01-30"] }
  ]
}

Transfert. Une fête empêchée de rang suffisant se déplace au prochain jour libre, puis de nouveau si celui-ci est occupé, formant une chaîne dans la fin de l’Avent, l’octave de Noël ou la Semaine sainte. Sans jour libre avant une limite, elle est non célébrée cette année. Une fête peut arriver d’une date antérieure (transferred_from/transferred_to), montrée dans saints à la nouvelle date avec from (§6). outcome distingue transferred, déplacée ailleurs, not-observed et omitted, restée sans prière.

Note : les dimanches repris suivent un autre mouvement. Point ouvert. Un dimanche empêché après l’Épiphanie ou la Pentecôte peut être repris des semaines plus tard avant l’Avent. Cela ressemble au transfert sans avoir la structure d’une fête, donc la chaîne ne convient pas. Ce cas non modélisé apparaît seulement à la date de célébration, sans lien de retour. Une relation resumes: reste ouverte.

5. Temps liturgiques et couleur

"season": { "id": "lent", "arc": "after-epiphany", "week": 3 }
// arc: 1962 counting arc, null for OF;  week: within the arc (see note)

Identifiants : advent · christmas · en 1962 : epiphany · septuagesima · passiontide · pentecost (arc after-pentecost) · dans les deux : lent · easter · forme ordinaire : ordinary. Le temps de l’Ascension est dans easter ; après Pentecôte en 1962, c’est pentecost et arc, sans identifiant distinct. Les semaines commencent à 1 et sont ancrées au dimanche ; la semaine d’un arc commençant en milieu de semaine, comme les jours des Cendres ou après l’Épiphanie, est la semaine 1. Le temps de Noël de la forme ordinaire dure jusqu’à la veille du Baptême ; en 1962 il cède au temps de l’Épiphanie le 6 janvier. Les temps déterminent couleur, chants de messe (§7), présence du Gloria, Alléluia et Te Deum et repli férie ou Commun.

Note : ce que compte week. En 1962, le compteur recommence par arc : after-epiphany et after-pentecost débutent chacun à 1, distingués par arc. Le nombre après Pentecôte varie de 23 à 28 par an ; les derniers dimanches après l’Épiphanie sont repris avant l’Avent (§4). Dans la forme ordinaire, le temps ordinaire garde une numérotation de 1 à 34 qui saute par-dessus Carême et Pâques (…8, [Carême/Pâques], 11…) ; arc vaut null.

Note : season donne la position célébrée, scalaire par choix. Un jour peut appartenir à deux cadres : christmas et octave, ou dimanche repris avant l’Avent mais originaire d’après l’Épiphanie. Un objet représente la position célébrée, l’octave reste séparée (§9) ; le cadre d’origine du dimanche repris est perdu, point ouvert (§4). Le cas est suffisamment rare.

Note : la couleur est { default, alternatives[] }. Gaudete et Lætare ajoutent le rose ; un Requiem est noir ou violet ; certaines vigiles ou messes votives diffèrent. Valeurs : blanc, rouge, vert, violet, rose, noir et or.

6. Commémoraisons et bloc saints

Un office inférieur empêché est conservé comme ensemble de prières dans l’office retenu, sans devenir une seconde messe.

• Composition : à la messe, deuxième ou troisième collecte, secrète et postcommunion ; à laudes et vêpres, antienne, verset et collecte ; à matines, parfois une neuvième leçon.
• Deux degrés : privileged (dimanches, fêtes de première classe, féries d’Avent et de Carême, Quatre-Temps, jours de l’octave de Noël, Litanies majeures), à laudes, vêpres et toutes les messes ; ordinary, seulement laudes, vêpres et messes basses, omis à la messe solennelle.
• Ordre et plafond : priorité aux privilégiés, puis à la classe supérieure, avec ordre fixe dans la classe ; liste tronquée par la règle au plafond d’oraisons. La troncature est elle-même une information.
• Jours n’admettant rien : dimanche des Rameaux, vigile de Pentecôte, plus grands jours. La liste est vide selon la règle, avec motif, ce qui diffère de l’absence de saint ce jour.

"commemorations": [
  { "name": { "la": "S. Agnetis … secundo", "en": "St Agnes, 2nd feast" },
    "rank": { "label": "commemoration", "precedence": 110 },
    "kind": "ordinary", "prayers": { "collect": { … } }, "id": "agnes-secundo" }
]

Note : plafond calculé et collectes impérées séparées. Le plafond dépend du jour et du temps, pas d’un constant 3. Une collecte impérée, ordonnée par l’évêque ou les rubriques, n’est pas une commémoraison de saint ; elle possède imperated_collects[] sur la messe.

Note : dernier évangile inclus, préface exclue. Lorsqu’une fête remplace un dimanche en 1962, l’évangile du dimanche commémoré devient le dernier évangile propre, choisi par le calendrier et inclus (last_gospel). La préface dépend du rang et du temps mais appartient à l’Ordinaire, donc exclue, avec au plus un libellé.

saints répond aux questions sur les fêtes. Une commémoraison correspond à un office écarté dans la préséance ; le saint principal n’est jamais dans saints.commemorated. Un office écarté n’est pas toujours commémoré :

Les clés du bloc sont les résultats, pour répondre aux questions courantes par un seul accès et ajouter de nouveaux résultats sans rupture. remembered du Martyrologe forme un troisième niveau indépendant de la résolution : la mémoire complète de l’Église pour cette date.

"saints": {
  "celebrated":   [ { "name": {…}, "id": "lawrence", "person": "lawrence", "rank": {…} } ],
  "commemorated": [ { "name": {…}, "id": "agnes-secundo", "rank": {…} } ],
  "remembered":   [ { "name": "St Tychicus" } ]  // + "note" with ?include=martyrology
}

7. Messe

Les propres, distincts de l’Ordinaire fixe, sont ordonnés ainsi : Introït · Collecte · Épître · Graduel/Trait/Alléluia · [Séquence] · Évangile · Offertoire · Secrète · Communion · Postcommunion. Plusieurs sont des lectures de l’Écriture : première et deuxième lectures et psaume dans la forme ordinaire ; épître et évangile en traditionnel. Les chants d’introït, graduel, offertoire et communion sont des antiennes propres. Chaque emplacement a un rôle, permettant une structure commune aux rites :

{ "role": "gospel", "ref": "Luc 14:16-24",
  "text": { "la": "In illo témpore…", "en": "…" },
  "edition": { "la": "vulgate", "en": "douay" } }  // which edition produced each text (ids per /liturgy/v1/translations)
// ref = uncopyrightable citation, present when known, independent of text + translation

Note : la traduction est un axe par texte, indépendant de la langue (§10). Seul le text biblique le porte ; ref, noms, rubriques et antiennes n’en dépendent pas. edition rapporte la traduction effectivement utilisée par langue après translations et le repli par défaut. Le client peut ainsi voir qu’un passage indisponible dans l’édition demandée a été fourni dans une autre. Toutes les éditions servies sont du domaine public et conservées en interne.

Note : readings[] est de longueur variable et ordonné. Un samedi des Quatre-Temps peut avoir six leçons, la vigile pascale une série de prophéties, douze anciennement et quatre en 1962 ; plusieurs entrées role: "lectio" se distinguent par leur position.

Note : chant entre les lectures et séquence. Le rôle unique interlection varie selon le temps : graduel, trait pénitentiel ou double Alléluia pascal. La séquence a son emplacement distinct après l’Alléluia : role: "sequence", obligation: obligatory | optional. Obligatoire à Pâques et Pentecôte ; Lauda Sion et Stabat Mater facultatifs ; Dies Irae lié au Requiem.

Une date, plusieurs messes. masses est une liste, même pour une seule messe :

• Multiplicité prescrite : trois messes de Noël, minuit, aurore et jour, et grandes vigiles ; toutes sont dites.
• Choix facultatif : mémoire facultative ou férie dans la forme ordinaire ; une seule est dite.
• Requiem prescrit : jour de Requiem, trois à la Commémoraison des fidèles défunts, inclus ; messes votives discrétionnaires et Requiem occasionnels exclus (Limites).

"masses": [
  { "id": "midnight", "name": {…}, "option_type": "prescribed", "colour": {…}, "readings": [ … ] },
  { "id": "dawn", "option_type": "prescribed", … }, { "id": "day", "option_type": "prescribed", … }
]
// option_type: prescribed (all said) | optional (a choice)

8. Office divin et Liturgie des Heures

Huit heures : matins · lauds · prime · terce · sext · none · vespers · compline. Prime est supprimée dans la forme ordinaire ; chaque calendrier annonce ses heures. Chacune comporte psaumes et cantiques encadrés d’antiennes, hymne, chapitre, verset, répons et collecte. Les cantiques évangéliques propres aux heures sont Benedictus à laudes, Magnificat aux vêpres, Nunc Dimittis à complies. Matines est plus développé : un ou trois nocturnes de psaumes et leçons, avec Te Deum les jours festifs.

{
  "hour": "vespers",
  "psalmody": [ { "antiphon": {…}, "psalm": { "ref": "Ps 109", "text": {…} } } ],
  "chapter": { "ref": "…", "text": {…} }, "hymn": {…}, "versicle": {…},
  "canticle": { "antiphon": {…}, "text": { "la": "Magnificat…", "en": "…" } },
  "collect": {…}, "commemorations": [ /* §6 — Lauds & Vespers only */ ]
}

Assemblage par couches : Propre → Communs applicables → Psautier, chaque élément se résolvant séparément, par exemple collecte du Propre et psaumes du Psautier.

Note : la couche du Commun est composée. titles est un ensemble ; ["martyr","bishop"] compose les deux Communs. Chaque Commun a plusieurs formulaires selon le temps. Il faut résoudre les Communs applicables et choisir le formulaire du temps.

Premières et secondes vêpres, concurrence. Une fête a des premières vêpres la veille et des secondes vêpres le jour même. À leur rencontre, la préséance (§4) détermine lesquelles sont chantées et si l’autre office est commémoré. « Vêpres du jour D » est ambigu : ce sont deux objets distincts.

Note : vêpres à sources partagées exclues. La concurrence peut prendre les psaumes d’un office et chapitre, hymne et collecte a capitulo d’un autre. L’assemblage Propre → Commun → Psautier ne peut pas exprimer cette division. Nous servons les vêpres résolues et leur résultat sans répartition des éléments.

9. Octaves, vigiles et jours des temps privilégiés

Octaves : une fête de premier rang prolongée huit jours ; chaque jour infra octavam et le dies octava a son rang et peut être empêché. En 1960, trois restent : Noël, Pâques et Pentecôte. Dans octave: { of, day }, day est une position ; la classe réelle est dans rank. Les jours de l’octave de Noël ne sont pas uniformes : 26 à 28 décembre de troisième classe, jour octave de deuxième.

Note : type d’octave exclu à partir de 1960. Avant 1955, les octaves étaient classées privilégiées, communes ou simples. En 1960, seules trois subsistent, donc pas de type. Une édition antérieure à 1955 (§2) aurait besoin d’octave_type.

Vigiles : veille liturgique d’une grande fête, jour séparé avec sa messe et son office, pouvant tomber dans une autre octave.

Note : les vigiles sont typées. vigil_type: ordinary, commémorée si empêchée ; privileged, veille de Noël précédant un dimanche ; paschal, vigile pascale et commencement du Triduum. Le rang appartient au jour (rank).

Jours du temporal des temps privilégiés : types de jours avec leurs propres messes, rang et commémoraison privilégiée (rank.cycle: "temporale"), distincts des simples féries : féries d’Avent depuis le 17 décembre, jours des antiennes « O » ; propres des jours de Carême ; Quatre-Temps ; Rogations, Litanies majeures du 25 avril et mineures, avec procession: true.

Note : litanie processionnelle non servie. La Litanie des Saints en procession est un quatrième type de contenu hors messe propre et heure de l’Office, sans emplacement dans §7/§8. Jour, messe et rang sont inclus ; procession: true le signale ; le texte de la litanie est exclu.

10. Texte multilingue

Toute chaîne lisible est une correspondance de langues { "la": …, "en": …, "fr": … } :

• Latin comme base : toujours présent, du domaine public, jamais filtré.
• Langues comme données : ajouter fr ou es ajoute une clé ; une requête peut limiter les langues, en gardant le latin.
• Référence et texte distincts : ref est un fait pouvant exister seul ; text en est le rendu traduisible, parfois absent.

Langue et traduction forment deux axes. La langue (Accept-Language) choisit la clé ; la traduction (paramètre translations) choisit, uniquement pour le text biblique, l’édition du domaine public qui remplit cette clé. Ainsi Accept-Language: en et translations=cpdv donnent le texte anglais CPDV. Les éditions sont des données : anglais douay ou cpdv, latin vulgate, chacune avec défaut par langue. Le choix résolu est rapporté dans chaque lecture par edition (§7) et au niveau de réponse par editions. Les textes non bibliques, noms, rubriques et antiennes, ont un rendu canonique unique par langue et ignorent cet axe. Toutes les éditions sont conservées en interne, sous forme de corpus du domaine public intégrés au service ; aucune n’est récupérée chez un tiers.

11. Saints

Deux niveaux. Une entrée de rite (§3) est sa célébration, avec date, rang et nom. Au-dessus se trouve une personne canonique, indexant le même saint dans les rites afin de voir tous les calendriers ensemble, y compris les dates différentes : Catherine de Sienne le 29 avril dans la forme ordinaire et le 30 avril en 1962 ; Éphrem le 9 juin et le 18 juin. La personne est un index ; les données de chaque rite restent distinctes. L’unification normalise les noms, retirant honorifiques et titres et rapprochant les variantes orthographiques, utilise une petite liste d’alias vérifiés et des identifiants propres aux rites si un nom normalisé est occupé. Les dates ne servent pas de clés d’identité, une réforme pouvant déplacer la fête d’un saint.

Personne dans tous les calendriers (GET /liturgy/v1/saints/john-of-the-cross) :

{
  "person": "john-of-the-cross", "name": { "la": "S. Ioannes a Cruce", "en": "St John of the Cross" },
  "calendars": {
    "traditional":     { "id": "ioannes-a-cruce", "date": "11-24", "rank": "class-3",
                        "titles": ["confessor","doctor"], "ref": "/liturgy/v1/calendars/traditional/saints/ioannes-a-cruce" },
    "ordinary": { "id": "john-of-the-cross", "date": "12-14", "rank": "memorial",
                        "titles": ["doctor"], "ref": "/liturgy/v1/calendars/ordinary/saints/john-of-the-cross" }
  }
}

Chaque bloc de rite porte id local et ref vers le bas ; l’entrée de rite porte person vers le haut (§3). Les deux espaces d’identifiants permettent toujours de poursuivre la navigation.

La recherche distingue les saints Jean par titres et dates des fêtes. La recherche globale montre les calendriers de chacun ; celle d’un rite ne liste que son sanctoral. Les résultats utilisent l’enveloppe de collection et Accept-Language pour le texte :

// GET /liturgy/v1/saints?q=john   (Accept-Language: en)
{ "results": [
    { "person": "john-the-baptist", "name": {…}, "titles": ["precursor"], "calendars": ["traditional","ordinary"],
      "feasts": [ { "date": "06-24", "kind": "nativity" }, { "date": "08-29", "kind": "beheading" } ] },
    { "person": "john-of-the-cross", "name": {…}, "titles": ["doctor"], "calendars": ["traditional","ordinary"] }
  ],
  "query": { "q": "john" }, "page": { "total": 2, "next": null } }

• Un résultat par personne ; feasts[] liste chaque occurrence, parfois plusieurs, comme Nativité et Décollation, jour octave ou fête secundo (§6). date est MM-DD pour les fêtes fixes ou anchor mobile (§2).
• Correspondance sur les clés de noms de chaque langue, sans diacritiques et avec base latine. q recherche le nom ; title et month sont des filtres séparés.
• Recherche dans un rite (/calendars/{cal}/saints) : identifiants locaux, dates, rangs et titres de ce rite uniquement ; un saint absent n’apparaît pas.

Limites : éléments non servis

• Chant et cérémonial, ainsi que l’Ordinaire fixe de la messe. Le propre et le calendrier qui le sélectionne sont servis.
• Premières vêpres (…/office/first-vespers) : dépendent de la résolution de concurrence non encore calculée ; le chemin renvoie 404 plutôt que des secondes vêpres sous un nom erroné. vespers et second-vespers du jour sont servis.
• Noms des saints uniquement anglais actuellement : le sanctoral intégré ne porte pas de noms latins ; les blocs name sont { en }, seule exception à la base latine des textes liturgiques. Les noms latins arriveront avec l’indexation des données de rite.
• Préface, appartenant à l’Ordinaire ; le dernier évangile propre d’un dimanche commémoré est servi (§6).
• Texte de litanie processionnelle, Rogations et Litanies majeures (§9) ; le jour reste inclus.
• Vêpres en concurrence à sources partagées (§8) : seules les vêpres résolues sont servies.
• Messes votives discrétionnaires, funérailles ou mariages occasionnels ; les jours de Requiem prescrits sont inclus (§7).
• Calendriers locaux ou propres au-delà des trois rites, tables de transfert et précepte par conférence et fêtes propres régionales, dont patrons affectant la préséance ; ces données viendront au fil du temps (§2).
• Éditions historiques arbitraires : seulement trois éditions fusionnées, aucun sélecteur d’année de rubriques ; l’axe edition reste futur (§2).
• Deux cadres simultanés de temps liturgique, notamment origine d’un dimanche repris (§5).
• Comput oriental julien ; Pâques grégorien est supposé (§2).
• Titres vernaculaires des jours du temporal : le latin est toujours présent ; le nom anglais est un ajout au mieux selon la source. Divinum Officium conserve les titres du temporal et des fêtes du Seigneur en latin ; environ un tiers des jours de 1962 et dominicains n’ont pas de nom anglais, même si lectures et Office sont traduits lorsqu’une version libre existe. Les fêtes sanctorales reçoivent leur nom anglais quand la source en a un.
• Calcul des transferts et omissions (§4/§6) : le moteur résout l’occurrence, office retenu et commémoraisons, sans encore la mécanique des transferts. saints.associated conserve indépendamment les associations fixes de la forme ordinaire ; resolution.displaced ne contient encore que commemorated. omitted, transferred, not-observed et chain sont dans la structure et seront remplis avec la résolution des transferts. Les tables DO Tabulae/Transfer sont intégrées pour cela. Une absence est renvoyée sans transfert supposé.

Questions ouvertes

• Clé du jour liturgique ou de date civile (§3) : structure des relations de débordement.
• Préséance conditionnelle (§4) : exposer la règle ou seulement son résultat ?
• Dimanches repris (§4) : relation resumes: distincte du transfert.

Sources

Classement des jours liturgiques · Commémoraison · Occurrence · Propre · Bréviaire romain · Calendrier romain général de 1960 · Rubriques générales de 1960 · romcal, travaux antérieurs de modèle de calendrier.

Provenance des données : toutes conservées en interne, sans appel tiers à l’exécution. Calendrier, propres et Office : corpus Divinum Officium du domaine public intégré. Martyrologe : édition de Baltimore de 1916 du domaine public, intégrée (data/martyrology/). Écriture : éditions du domaine public intégrées, Vulgate clémentine en latin et Nova Vulgata lorsque libre ; Douay-Rheims, révision Challoner, et Catholic Public Domain Version en anglais. Les références sont des faits non protégeables par droit d’auteur. Rien n’est récupéré d’un service externe au moment de la requête.