Liturgia

Questo dominio è vasto e complesso. Le note devono restare concise per essere utili.

Il dominio dei dati liturgici e la sua rappresentazione nell’API. È un modello di dominio, non un resoconto delle realizzazioni. Le Note segnalano scelte o limiti deliberati delle strutture; i Limiti elencano ciò che non viene fornito.

Cosa fornisce l’API

Per (calendar, region, date), risolve e restituisce:

1. Contesto del giorno: data civile e giorno della settimana, tempo liturgico e settimana, cicli dell’anno liturgico (lezionario della forma ordinaria A/B/C, feriale I/II, settimana del salterio), stato di precetto.
2. Celebrazione: identità del giorno, nome multilingue, grado, colore, slug del santo, categorie dei Comuni e appartenenza a un’ottava.
3. Commemorazioni: altri santi inclusi con preghiere aggiunte.
4. Feste di oggi: tutti i santi relativi alla data, distinti per esito (celebrato, commemorato, omesso, arrivato), per rispondere alle domande sulle feste senza analizzare la risoluzione (§6).
5. Messa o Messe: propri dall’Introito al Postcommunio e letture con citazione e testo; più Messe nei giorni che le prevedono, come Natale, vigilie e Requiem.
6. Ufficio: otto ore assemblate, con salmi, antifone, inno, capitolo, cantico e colletta; primi e secondi Vespri distinti.
7. Risoluzione, facoltativa: motivo della scelta dell’ufficio e uffici commemorati, omessi, trasferiti o non celebrati.
8. Santi: accessibili per rito (/{calendar}/saints/{id}).

Ogni testo leggibile è una mappa { la, en, … } con il latino come base. La liturgia è una risoluzione: temporale, tempi ancorati alla Pasqua, e santorale, feste fisse, propongono un ufficio; la precedenza, occorrenza nel giorno e concorrenza ai suoi confini, sceglie l’ufficio e il destino degli altri. L’ufficio scelto fornisce Messa e Ufficio, assemblati Proprio → Comune → Salterio.

Endpoint

Regola di collocazione. Risorse comuni ai riti al livello superiore (/calendars, /saints, /regions); risorse di rito sotto /calendars/{cal}. Un giorno restituisce un riepilogo leggero. Gli strati pesanti arrivano inline tramite ?include= per chiamate in lotto, oppure come sottorisorse indirizzabili per collegamenti diretti. Entrambe le forme esistono, vedi Inclusioni.

Inclusioni. ?include=masses,office,resolution,martyrology inserisce inline gli strati pesanti nel giorno o in ogni giorno di un intervallo o anno. La vista mensile delle letture usa così una chiamata, anziché 1 + N. Le URL (…/masses, …/office/{hour}, …/resolution) restano per collegamenti diretti. Senza include il giorno contiene solo riepilogo e links.

Le raccolte (/days?from..to, /years/{label} e le due ricerche /saints) restituiscono un involucro, mai un array nudo, per mostrare query, totali, paginazione e limiti applicati:

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

Gli array dentro una risorsa (saints.*, readings) sono sottocampi limitati e restano senza involucro.

Identificativi e negoziazione.

• Date: un giorno specifico è ISO YYYY-MM-DD; una festa fissa ricorrente usa MM-DD; una festa mobile usa anchor (§2). L’anno liturgico ha identità propria: {label} è l’intervallo canonico YYYY-YYYY da Avvento ad Avvento, per esempio 2025-2026, evitando ambiguità di inizio o fine. YYYY solo, l’anno che comincia nell’Avvento di YYYY, o una data contenuta, dà reindirizzamento 301 all’intervallo: un anno, una URL.
• region è un affinamento facoltativo della query. Assente o sconosciuto torna a general, l’editio typica, senza errore e con region_default_applied. Un identificativo cal errato nel segmento strutturale {cal} restituisce 404.
• Gli identificativi del percorso ignorano maiuscole e minuscole. {cal} (ordinary/traditional/dominican, senza alias), {hour} e {mass} risolvono anche come Traditional, Vespers o MIDNIGHT. Un identificativo davvero sconosciuto restituisce 404. La tolleranza aiuta il chiamante.
• Lingua tramite Accept-Language, non percorso o parametro. Il latino è base, la selezione è additiva e 406 non si verifica mai. Le risposte inviano Vary: Accept-Language.
• Traduzione come secondo asse distinto dalla lingua: esistono più edizioni bibliche per lingua, inglese douay e cpdv, latino vulgate clementina, con Nova Vulgata futura. Il parametro facoltativo translations le seleziona: editions= è il nome canonico, uguale al campo di risposta; translations= è alias. Lista di ID separati da virgole (editions=cpdv,vulgate), massimo uno per lingua, applicata solo al text delle letture. Citazioni e testi non biblici sono indipendenti. Valore assente o ignoto usa il predefinito della lingua senza errore, indicato con editions e warnings nelle raccolte. Ogni text risolto porta l’edition che lo ha prodotto. /liturgy/v1/translations elenca le edizioni; il set scelto entra in Vary e ETag. Un parametro serve perché il tag HTTP sceglie una lingua, non un’edizione editoriale; sovraccaricarlo con en-x-cpdv non è standard e non è memorizzabile correttamente dai CDN sensibili alle lingue.
• Slug dei santi in due spazi: id di rito e person canonico. I collegamenti incrociati sono obbligatori: la voce di rito ha person verso l’alto, calendars{} della persona ha ref verso il basso. Nessun ID è un vicolo cieco.

Cache. Una risposta è funzione pura di (cal, date, region, Accept-Language, translations, data-version). ETag incorpora tutti e sei, evitando che un CDN basato su percorso e Vary serva la variante errata. Una correzione o nuova tabella regionale incrementa data-version e cambia gli ETag coinvolti. Questo invalida anche giorni passati, a lunga cache ma mai immutable. If-None-Match restituisce 304.

Versioni e ciclo di vita. /liturgy/v1 è additiva entro la versione principale: campi aggiunti, mai rimossi o ritipizzati. Edizioni e regioni arrivano come dati (§2). Una modifica incompatibile usa /liturgy/v2; la vecchia versione riceve una data di rimozione con Deprecation e Sunset, almeno dodici mesi di preavviso. I campi deprecati hanno un collegamento Deprecation nei documenti. Nulla in v1 cambia silenziosamente.

Gli errori sono application/problem+json (RFC 9457), con URI type stabile per le macchine, title, status, detail, instance:

• 400: input malformato, data non canonica YYYY-MM-DD senza zeri o include fuori dall’insieme consentito.
• 404: {cal}, {person}, {id} sconosciuto o {hour}/{mass} non esposto dal giorno.
• 405: verbo diverso da GET su percorso valido; sola lettura con Allow: GET.
• 406: mai restituito, il latino soddisfa ogni Accept-Language.
• 422: richiesta ben formata fuori dalla durata supportata dall’edizione.
• 429: limite di richieste, con Retry-After.
• region errata, edizione translations ignota o from/to oltre il limite non danno mai errore: ripiego o riduzione, valore applicato ripetuto (region_default_applied/editions) e warnings nelle raccolte.

Convenzioni.

• Tipo di media application/json; contratto canonico per macchine nel documento OpenAPI 3.1 (/liturgy/v1/openapi.json), da cui generare client e fonte autorevole per le strutture qui abbozzate.
• Sola lettura e idempotenza. Tutti gli endpoint sono GET, quindi sicuri, idempotenti e memorizzabili. Senza scritture non servono chiavi di idempotenza.
• Autenticazione e limiti. Chiave bearer (Authorization: Bearer gianna_…), creata nell’app da qualsiasi account con POST /api/keys, mostrata una volta e gestita o revocata con GET/DELETE /api/keys. Vale anche una sessione browser autenticata. I dati sono gratuiti e richiedono un account, senza piano. Non autenticato: 401 con WWW-Authenticate: Bearer; sessione anonima: 403. Indice, openapi.json e feed feasts.ics sono pubblici senza chiave. Limiti a finestre fisse per famiglia con 429, Retry-After e RateLimit-Limit sul 429; il primo limite IP è del proxy inverso. Autenticazione e piano non cambiano la rappresentazione o la chiave di cache.
• Intestazioni di cache. Ogni risposta ha ETag, Cache-Control: public, max-age=… limitato e stale-while-revalidate. Date passate hanno durata lunga perché la risposta rubricale è stabile, ma non immutable: correzioni e nuove tabelle region possono cambiare risoluzioni storiche. ETag, legato a versione dati, regione e lingue, consente l’invalidazione; il client rivalida con If-None-Match. Le risposte sono public perché uguali per ogni chiamante, ma l’accesso è controllato: una cache periferica del gestore deve richiedere la chiave prima di servire dalla cache. Non mettere una cache condivisa anonima davanti a /liturgy/v1.
• Oggi. Nessuna risorsa server « oggi »: il giorno segue la data civile del chiamante, che un server UTC non deve decidere. I client risolvono la data locale e la chiedono esplicitamente (…/days/2026-06-09). Accept-Language e region non implicano date.
• Controllo di costo di ?include. include è rifiutato con 400 su raccolte di più giorni per office e masses oltre un piccolo intervallo, per esempio 31 giorni, evitando risposte enormi per un anno. Usa le sottorisorse giornaliere. resolution, leggero, resta sempre includibile.

1. Calendari e riti

Ogni sistema ha santorale, precedenza, propri ed edizione propri. La data si risolve indipendentemente in ciascuno; la precedenza è per rito (§4).

Ogni rito ha un ID stabile, ordinary, traditional o dominican, senza alias, e indica se espone un Ufficio.

Nota: una nomenclatura in tutto il prodotto. I tre nomi valgono per preferenza del calendario familiare, /api/prefs, strumento liturgico dell’agente e testi dell’interfaccia. Vecchi ID e alias (roman-ordinary, roman-1962, general, of, tlm, op) sono stati ritirati con una modifica incompatibile prima dei client esterni: restituiscono 404, sono rifiutati dalle preferenze e la migrazione 0029 ha riscritto i dati. Sinonimi umani, « TLM », « Messa latina », « forma straordinaria », « Novus Ordo », sono linguaggio naturale, mappato dal modello al nome canonico. Gli analizzatori accettano solo i tre, senza distinzione di maiuscole.

2. Input della risoluzione: rito, anno, regione

Temporale: mobile, ancorato alla Pasqua, da cui Settuagesima, Ceneri, Ascensione, Pentecoste e numero delle domeniche; l’Avvento ancora l’altra estremità. Dipende dall’anno.

Nota: Pasqua è calcolata con il computo gregoriano occidentale. Tutte le date mobili ne dipendono; è fissata a un algoritmo nominato e tabella di regressione di date note. Computo orientale giuliano e calcoli storici divergenti sono esclusi.

Tre tipi di santorale:

• Fisso: mese e giorno indipendenti dall’anno, come Natale il 25 dicembre. La maggioranza.
• Mobile: regola ancorata al temporale, come Santa Famiglia la domenica nell’ottava di Natale altrimenti 30 dicembre, o Sacro Cuore il venerdì dopo l’ottava del Corpus Domini. Porta anchor.
• Mobile e diverso per rito: regola distinta, come Cristo Re, ultima domenica prima dell’Avvento nella forma ordinaria e ultima domenica d’ottobre nel 1962. L’ancoraggio è proprietà di (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

Nota: differenze stratificate internamente, risultati fusi esposti. Una versione è tabella base e strati di riforma dal 1568 al 1960: tecnica di costruzione, non asse esposto. Nessun selettore dell’anno delle rubriche, quindi niente « 1939 »; la scelta d’edizione è futura (Limiti).

Regione: tre effetti rubricali, due modellati: feste trasferite alla domenica secondo la conferenza, Epifania, Ascensione e Corpus Domini, e feste di precetto (§3a). Conferisce anche feste proprie, patronali, non modellate (Limiti).

Nota: regione più limitata del ruolo reale della conferenza. Le feste proprie influenzano la precedenza, una solennità patronale cambia il giorno, ma modelliamo solo trasferimento e precetto. general è l’editio typica: mantiene Ascensione, Epifania e Corpus Domini nel giorno feriale, anche se gran parte del mondo li celebra di domenica. La risposta predefinita è dell’edizione tipica, non di un paese. Le tabelle delle conferenze sono dati aggiunti nel tempo.

Anno liturgico: inizia alla prima domenica d’Avvento; un anno civile ne attraversa due. I cicli della forma ordinaria dipendono da esso:

"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
}

Nota: i cicli cambiano in date diverse. Il domenicale cambia all’Avvento; il feriale, I negli anni civili dispari, al 1° gennaio. Un solo starts non basta a ricavarli; sono forniti entrambi risolti. Cicli null per il 1962, annuale. psalter_week è null anche in molti altri casi: solennità e feste prendono la settimana I; ottave, ultimi giorni d’Avvento e Settimana santa sovrascrivono il salterio. È un suggerimento per giorni ordinari, non un semplice 1–4.

3. Il giorno liturgico

L’endpoint del giorno restituisce riepilogo, nucleo leggero e collegamenti. Ufficio, propri completi e risoluzione sono richieste separate, secondo la tabella. Il riepilogo:

{
  "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": "…" }
}

Nota: registri separati in saints. celebrated e commemorated sono esiti liturgici di QUESTO calendario; una feria non è un santo e non compare. associated è l’indice dei santi a data fissa del calendario scelto, per non perdere l’associazione a una festa per precedenza. remembered è il Martirologio Romano, TUTTI i santi della data, spesso da 5 a 15, celebrati o no altrove. L’edizione di pubblico dominio del 1916 è integrata: non comprende santi canonizzati dopo, presenti invece nello strato del calendario; segue le date del calendario antico dove divergono. Gli esiti futuri transferred e omitted arriveranno come nuove chiavi. remembered[].name è solo inglese (Limiti). I nomi sono sempre presenti; l’elogio note si include con ?include=martyrology, pesante e limitato come masses e office: 90 giorni di elogi occuperebbero gran parte della risposta. Le risposte sono compresse gzip quando negoziato.

Nota: il riepilogo elenca descrittori delle Messe. masses[] contiene il leggero { id, name, colour, option_type }, senza propri, disponibili tramite masses_url o ?include=masses. Un conteggio solo richiederebbe un secondo accesso per le identità. Inoltre celebration.colour è il colore del giorno e può differire da quello di ogni Messa: un Requiem nero in un giorno bianco (§7). colour per Messa è autorevole per la visualizzazione del giorno.

Nota: chiave di data civile e due fatti distinti del sabato sera. Questione aperta. Usiamo data civile per evitare ambiguità nella richiesta del 2026-06-09 e relazioni esplicite separate per il passaggio serale: primi Vespri, rubricali, Ufficio di domani questa sera (liturgical_evening.belongs_to), e Messa anticipata, canonica, la Messa del sabato sera assolve il precetto domenicale (anticipated_mass). L’Ufficio può essere di domani mentre la Messa è di oggi. La struttura esatta resta aperta.

3a. Precetto: dipendente dalla regione, non deducibile dal grado

"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
}

Nota: tre stati e identificativo per macchine. Un booleano non porta la regola di precetto parziale, che decade sabato o lunedì, senza cambiare ogni anno. reason_code affianca il testo. A general, l’edizione tipica dà il diritto universale: ogni domenica e le dieci feste del canone 1246, otto fisse e Ascensione e Corpus Domini mobili, nominate da reason. Non si deduce dal grado: molte solennità non hanno precetto. Decadenze e trasferimenti regionali (reason_code, lapsed) arrivano con le tabelle.

Celebrazione

{
  "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)
}

Nota: slug di rito e collegamento superiore person. Lo stesso santo può avere grado, nome o data diversa per rito. id identifica la celebrazione del rito; person collega obbligatoriamente alla scheda canonica comune (§11), il cui calendars{} rinvia verso il basso. I due spazi di slug non collidono, perché ogni ID è abbinato all’altro.

4. Grado, precedenza e risoluzione

La parte più codificata pone due domande: occorrenza, due uffici nella stessa data e chi celebrare, commemorare, omettere o trasferire; concorrenza, secondi Vespri di un ufficio e primi del successivo (§8).

Gradi diversi per rito. Nel 1962 e domenicano: quattro classi I–IV, commemorazioni, feria. Classi di feste e giorni, domenica, feria, vigilia, giorno d’ottava, si intrecciano: feria di I classe precede festa di I; domenica di II precede festa di III, poi commemorata. Nella forma ordinaria: Solennità > Festa > Memoria > Memoria facoltativa > Giorno feriale, tabella del 1969.

Nota: le domeniche hanno più gradi. Nel 1962 quelle di I classe, Avvento, Quaresima e Passione, ammettono quasi nulla; quelle di II, verdi, possono cedere a una festa di II. Analogo nella forma ordinaria: domeniche di Avvento, Quaresima e Pasqua davanti alle feste; domeniche ordinarie cedono alle feste del Signore. Il grado di una domenica porta la classe specifica.

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

Note su rank.

• cycle è il ciclo proponente: domenica o feria è temporale pur essendo classe di giorno; la distinzione è in label.
• precedence confronta entro una risoluzione, un rito e un giorno. Confrontare riti diversi non ha senso (§1).
• precedence ordina, non decide. Questione aperta. Alcune regole sono condizionali: una festa del Signore sostituisce una domenica ordinaria, ma non Avvento, Quaresima o Pasqua. Due interi non bastano; il motore usa tutta la tabella, l’intero è il risultato. Esporre regola o solo esito resta aperto.
• Il giorno non ha un unico grado scalare. Messa, ore diurne e i due Vespri possono risolvere a uffici diversi, indirizzabili separatamente (§7/§8).

La risoluzione facoltativa espone la decisione:

"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"] }
  ]
}

Trasferimento. Una festa impedita di grado sufficiente si sposta al prossimo giorno libero, ancora se occupato, formando una catena a fine Avvento, ottava di Natale e Settimana santa. Senza posto prima di una scadenza, non si osserva quest’anno. Può arrivare da una data precedente (transferred_from/transferred_to), mostrata in saints della nuova data tramite from (§6). outcome distingue transferred, spostata altrove, not-observed e omitted, rimasta senza preghiere.

Nota: domeniche riprese come movimento diverso. Questione aperta. Una domenica impedita dopo Epifania o Pentecoste può essere ripresa settimane dopo, prima dell’Avvento. Somiglia a un trasferimento, ma non ha forma di festa, quindi la catena non si adatta. Non modellata: compare alla data celebrata, senza collegamento indietro. Una relazione resumes: resta aperta.

5. Tempi e colore

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

ID: advent · christmas · nel 1962: epiphany · septuagesima · passiontide · pentecost (arco after-pentecost) · in entrambi: lent · easter · forma ordinaria: ordinary. Il tempo dell’Ascensione è in easter; il tempo dopo Pentecoste del 1962 è pentecost con arc, senza ID distinto. Le settimane partono da 1 e sono ancorate alla domenica; quella di inizio arco a metà settimana, Ceneri o giorni dopo Epifania, è 1. Il Natale della forma ordinaria dura fino alla vigilia del Battesimo; nel 1962 cede all’Epifania il 6 gennaio. I tempi determinano colore, cambi di canti (§7), Gloria, Alleluia, Te Deum e ripiego feriale o sul Comune.

Nota: cosa conta week. Nel 1962 ricomincia per arco: after-epiphany e after-pentecost iniziano da 1, distinti da arc. Dopo Pentecoste si contano da 23 a 28 settimane annue; ultime domeniche dopo Epifania riprese prima dell’Avvento (§4). Nella forma ordinaria il tempo ordinario è una numerazione 1–34 che salta Quaresima e Pasqua (…8, [Quaresima/Pasqua], 11…); arc null.

Nota: season è la posizione celebrata, scalare per scelta. Un giorno può avere due cornici: christmas e ottava, o domenica ripresa prima dell’Avvento originaria dopo Epifania. Un oggetto indica la posizione celebrata; ottava separata (§9). L’origine della domenica ripresa è persa, questione aperta (§4). Caso abbastanza raro.

Nota: colore come { default, alternatives[] }. Gaudete e Laetare aggiungono rosa; Requiem nero o viola; alcune vigilie e votive differiscono. Valori: bianco, rosso, verde, viola, rosa, nero, oro.

6. Commemorazioni e blocco saints

Un ufficio inferiore impedito resta come insieme di preghiere nell’ufficio scelto, senza diventare una seconda Messa.

• Composizione: Messa, seconda o terza colletta, segreta, postcommunio; Lodi e Vespri, antifona, versetto, colletta; Mattutino, talvolta nona lezione.
• Due gradi: privileged, domeniche, feste di I classe, ferie di Avvento e Quaresima, Quattro Tempora, giorni dell’ottava di Natale e Litanie maggiori, a Lodi, Vespri e tutte le Messe; ordinary, solo Lodi, Vespri e Messe lette, omesso alla Messa solenne.
• Ordine e limite: privilegiati prima, poi classe superiore, ordine fisso nella classe; troncamento secondo la regola al limite di orazioni, che è esso stesso informazione.
• Giorni che non ne ammettono: Domenica delle Palme, vigilia di Pentecoste, giorni maggiori; lista vuota per regola, con motivo, diversa dall’assenza di santi nella data.

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

Nota: limite calcolato e collette imperate separate. Il limite dipende da giorno e tempo, non è sempre 3. Una colletta imperata, ordinata dal vescovo o dalle rubriche, non è commemorazione di santo: usa imperated_collects[] sulla Messa.

Nota: ultimo Vangelo incluso, prefazio escluso. Quando una festa sostituisce una domenica nel 1962, il Vangelo della domenica commemorata diventa ultimo Vangelo proprio, scelto dal calendario e incluso (last_gospel). Il prefazio dipende da grado e tempo ma appartiene all’Ordinario, quindi escluso, al massimo un’etichetta.

saints risponde alle domande sulle feste. La commemorazione è l’ufficio non scelto dalla precedenza; il santo principale non è in saints.commemorated. L’ufficio impedito non è sempre commemorato:

Il blocco usa chiavi per esito, così la domanda « chi si celebra oggi? » richiede un solo accesso e nuovi esiti ampliano la struttura senza romperla. remembered del Martirologio è un terzo livello indipendente dalla risoluzione: la memoria completa della Chiesa per la data.

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

7. Messa

I propri, distinti dall’Ordinario fisso, sono ordinati: Introito · Colletta · Epistola · Graduale/Tratto/Alleluia · [Sequenza] · Vangelo · Offertorio · Segreta · Comunione · Postcommunio. Alcuni sono letture bibliche, prima e seconda e salmo nella forma ordinaria, epistola e Vangelo nel tradizionale. Introito, Graduale, Offertorio e Comunione sono antifone proprie. Ogni posizione ha un ruolo, consentendo la stessa struttura per i riti:

{ "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

Nota: traduzione per testo, indipendente dalla lingua (§10). Solo text biblico la porta; ref, nomi, rubriche e antifone no. edition riporta la versione davvero usata per lingua dopo translations e ripiego predefinito. Un client vede così se il passo non disponibile nell’edizione richiesta è arrivato da un’altra. Tutte le edizioni sono di pubblico dominio e interne.

Nota: readings[] ha lunghezza variabile e ordine. Un sabato delle Tempora può avere sei lezioni; la Veglia pasquale una serie di profezie, dodici anticamente e quattro nel 1962. Entrate multiple role: "lectio" si distinguono per posizione.

Nota: canto interlezionale e sequenza. interlection varia per tempo: Graduale, Tratto penitenziale, doppio Alleluia pasquale. La sequenza è posizione distinta dopo l’Alleluia: role: "sequence", obligation: obligatory | optional. Obbligatoria a Pasqua e Pentecoste; Lauda Sion e Stabat Mater facoltativi; Dies Irae legato al Requiem.

Una data, più Messe. masses è una lista, anche per una sola Messa:

• Molteplicità prescritta: tre di Natale, mezzanotte, aurora e giorno, e grandi vigilie; tutte celebrate.
• Scelta facoltativa: memoria facoltativa o feria nella forma ordinaria; una sola celebrata.
• Requiem prescritto: giorno di Requiem, tre per i fedeli defunti, incluso; votive discrezionali e Requiem occasionali esclusi (Limiti).

"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. Ufficio divino e Liturgia delle Ore

Otto ore: matins · lauds · prime · terce · sext · none · vespers · compline. Prima è soppressa nella forma ordinaria; un calendario dichiara le ore. Ciascuna comprende salmi e cantici con antifone, inno, capitolo, versetto, responsorio, colletta. Cantici evangelici propri: Benedictus alle Lodi, Magnificat ai Vespri, Nunc Dimittis a Compieta. Mattutino è più ampio: uno o tre notturni con salmi e lezioni, Te Deum nei giorni festivi.

{
  "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 */ ]
}

Assemblaggio per strati: Proprio → Comuni applicabili → Salterio, con ripiego indipendente di ogni elemento, per esempio colletta dal Proprio e salmi dal Salterio.

Nota: il Comune è composto. titles è un insieme; ["martyr","bishop"] compone entrambi i Comuni. Ciascuno ha più formulari per tempo: risolvi i Comuni applicabili e scegli il formulario stagionale.

Primi e secondi Vespri, concorrenza. Una festa ha primi Vespri la sera prima e secondi il giorno stesso. Alla sovrapposizione, la precedenza (§4) decide quali cantare e se commemorare l’altro ufficio. « Vespri del giorno D » è ambiguo; sono due oggetti distinti.

Nota: Vespri con fonti divise esclusi. La concorrenza può usare salmi di un ufficio e capitolo, inno e colletta a capitulo di un altro. Proprio → Comune → Salterio non esprime questa divisione. Forniamo Vespri risolti ed esito, senza divisione degli elementi.

9. Ottave, vigilie e giorni dei tempi privilegiati

Ottave: festa di primo grado prolungata otto giorni; ogni giorno infra octavam e dies octava ha grado proprio e può essere impedito. Nel 1960 restano tre: Natale, Pasqua, Pentecoste. In octave: { of, day }, day è posizione; la classe reale è in rank. I giorni di Natale non sono uniformi: 26–28 dicembre di III classe, giorno dell’ottava di II.

Nota: tipo d’ottava escluso dal 1960. Prima del 1955 erano privilegiate, comuni o semplici; nel 1960 restano tre, senza type. Un’edizione pre-1955 (§2) richiederebbe octave_type.

Vigilie: vigilia liturgica di una grande festa, giorno distinto precedente con propria Messa e Ufficio; può cadere in un’altra ottava.

Nota: vigilie tipizzate. vigil_type: ordinary, commemorata se impedita; privileged, vigilia di Natale davanti a una domenica; paschal, Veglia pasquale e inizio del Triduo. Il grado appartiene al giorno (rank).

Giorni del temporale dei tempi privilegiati: tipi con Messe proprie, grado e commemorazione privilegiata (rank.cycle: "temporale"), oltre alle ferie semplici: ferie di Avvento dal 17 dicembre, giorni delle antifone « O »; propri feriali di Quaresima; Quattro Tempora; Rogazioni, Litania maggiore il 25 aprile e minori, con procession: true.

Nota: litania processionale non fornita. Le Litanie dei Santi in processione sono un quarto contenuto fuori da proprio della Messa e ora d’Ufficio, senza posto in §7/§8. Giorno, Messa e grado inclusi; procession: true lo segnala; testo della litania escluso.

10. Testo multilingue

Ogni stringa leggibile è una mappa di lingue { "la": …, "en": …, "fr": … }:

• Latino come base: sempre presente, pubblico dominio, mai filtrato.
• Lingue come dati: aggiungere fr o es aggiunge una chiave; una richiesta può limitare le lingue conservando il latino.
• Citazione e testo distinti: ref è un fatto autonomo; text è il suo testo traducibile, talvolta assente.

Lingua e traduzione sono due assi. Lingua (Accept-Language) sceglie la chiave; traduzione, parametro translations, sceglie solo per text biblico l’edizione di pubblico dominio. Accept-Language: en e translations=cpdv danno inglese CPDV. Le edizioni sono dati, inglese douay o cpdv, latino vulgate, con predefiniti per lingua. La scelta risolta è indicata su ogni lettura con edition (§7) e in risposta con editions. Stringhe non bibliche, nomi, rubriche e antifone hanno un solo testo canonico per lingua. Tutte le edizioni sono interne, corpus di pubblico dominio integrati nel servizio; nessuna viene recuperata da terzi.

11. Santi

Due livelli. Una voce di rito (§3) è la celebrazione di quel rito con data, grado e nome. Sopra c’è una persona canonica che indicizza lo stesso santo tra riti e mostra tutti i calendari, anche con date differenti: Caterina da Siena, forma ordinaria 29 aprile e 1962 30 aprile; Efrem 9 giugno e 18 giugno. La persona è un indice; i dati di rito restano distinti. L’unificazione normalizza nomi, rimuove onorifici e titoli, riunisce varianti ortografiche, usa pochi alias verificati e identificativi di rito distinti se il nome normalizzato è già occupato. Le date non sono chiavi d’identità, perché una riforma può spostare la festa.

Persona in tutti i calendari (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" }
  }
}

Ogni blocco di rito porta id locale e ref verso il basso; la voce di rito porta person verso l’alto (§3). I due spazi di slug non lasciano il client senza seguito.

La ricerca distingue i vari santi Giovanni con titoli e date delle feste. La globale mostra i calendari che li celebrano; quella di rito solo il santorale specifico. Risultati nell’involucro di raccolta, testo tramite Accept-Language:

// 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 risultato per persona, feasts[] per ogni occorrenza, anche più d’una: Natività e Decollazione, giorno d’ottava, festa secundo (§6). date è MM-DD fisso o anchor mobile (§2).
• Corrispondenza su chiavi di nome di tutte le lingue, senza diacritici e con base latina. q confronta il nome; title e month sono filtri separati.
• Ricerca di rito (/calendars/{cal}/saints): slug locali, date, grado e titoli del rito; un santo assente non appare.

Limiti: elementi non forniti

• Canto e cerimoniale, Ordinario fisso della Messa; sono serviti proprio e calendario che lo seleziona.
• Primi Vespri (…/office/first-vespers): dipendono dalla concorrenza non ancora calcolata. Percorso 404, per non presentare secondi Vespri con nome errato. vespers e second-vespers del giorno sono serviti.
• Nomi dei santi solo inglesi per ora: il santorale integrato non ha nomi latini; i blocchi name sono { en }, unica eccezione alla base latina dei testi liturgici. Il latino arriverà indicizzando i dati di rito.
• Prefazio, nell’Ordinario; l’ultimo Vangelo proprio della domenica commemorata è incluso (§6).
• Testo della litania processionale, Rogazioni e Litanie maggiori (§9); il giorno resta incluso.
• Vespri in concorrenza con fonti divise (§8): sono serviti quelli risolti, non la divisione.
• Messe votive discrezionali, funebri o nuziali occasionali; giorni di Requiem prescritti inclusi (§7).
• Calendari locali o propri oltre i tre riti, tabelle di trasferimento e precetto delle conferenze e feste regionali proprie, patronali che influenzano la precedenza. Dati nel tempo (§2).
• Edizioni storiche arbitrarie: solo le tre fuse; niente selettore d’anno delle rubriche. Asse edition futuro (§2).
• Due cornici stagionali simultanee, origine di domenica ripresa (§5).
• Computo orientale giuliano: Pasqua gregoriana assunta (§2).
• Titoli vernacolari dei giorni del temporale: latino sempre presente, nome inglese fornito nei limiti della fonte. Divinum Officium mantiene in latino titoli temporali e feste del Signore; circa un terzo dei giorni 1962 e domenicani non ha nome inglese, mentre letture e Ufficio sono tradotti se esiste una versione libera. Le feste santorali ricevono nomi inglesi quando presenti nella fonte.
• Calcolo di trasferimenti e omissioni (§4/§6): il motore risolve occorrenza, ufficio scelto e commemorazioni, ma non ancora trasferimenti. saints.associated conserva le associazioni fisse della forma ordinaria; resolution.displaced contiene ancora solo commemorated. omitted, transferred, not-observed e chain sono previsti nella struttura e saranno riempiti con la risoluzione dei trasferimenti. Le tabelle DO Tabulae/Transfer sono integrate per questo. Restituiamo assenza senza ipotizzare trasferimenti.

Questioni aperte

• Chiave del giorno liturgico o data civile (§3): forma delle relazioni serali.
• Precedenza condizionale (§4): esporre regola o solo esito?
• Domeniche riprese (§4): relazione resumes: distinta dal trasferimento.

Fonti

Grado dei giorni liturgici · Commemorazione · Occorrenza · Proprio · Breviario Romano · Calendario Romano Generale del 1960 · Rubriche generali del 1960 · romcal, precedenti del modello di calendario.

Provenienza dei dati: tutti interni, senza chiamate a terzi in esecuzione. Calendario, propri e Ufficio: corpus Divinum Officium di pubblico dominio integrato. Martirologio: edizione di Baltimora del 1916 di pubblico dominio, integrata (data/martyrology/). Scrittura: edizioni integrate di pubblico dominio, latino Vulgata Clementina e Nova Vulgata dove libera; inglese Douay-Rheims, revisione Challoner, e Catholic Public Domain Version. Le citazioni sono fatti non protetti da diritto d’autore. Nulla viene recuperato da un servizio esterno alla richiesta.