Liturgia

Es un ámbito amplio y complejo. Estas notas deben mantenerse concisas para resultar útiles.

El ámbito de los datos litúrgicos y cómo lo representa esta API. Un modelo del dominio, no un registro de lo construido. Las Notas indican decisiones o límites deliberados de la estructura; los Límites enumeran lo que no ofrecemos.

Qué proporciona la API

Para (calendar, region, date), resuelve y devuelve:

1. Contexto del día: fecha civil y día de la semana, tiempo litúrgico (y semana), ciclos del año litúrgico (leccionario de la forma ordinaria A/B/C, entre semana I/II, semana del salterio), estado de precepto.
2. Celebración: qué se celebra: nombre multilingüe, rango, color, identificador textual del santo, categorías del Común, pertenencia a una octava.
3. Conmemoraciones: otros santos incluidos mediante oraciones añadidas.
4. Fiestas de hoy: todos los santos relacionados con esta fecha, marcados por resultado (celebrado / conmemorado / omitido / trasladado aquí), para responder de quién es la fiesta sin analizar la resolución (§6).
5. Misa o Misas: propios (Introito … Poscomunión) y lecturas (referencia y texto); varias cuando hay más de una en el día (Navidad, vigilias, Réquiem).
6. Oficio: las ocho horas ensambladas (salmos, antífonas, himno, capítulo, cántico, colecta), con distinción entre primeras y segundas Vísperas.
7. Resolución (opcional): por qué prevaleció este oficio: quién fue conmemorado, omitido, trasladado o no celebrado.
8. Santos: consultables por rito (/{calendar}/saints/{id}).

Todo texto legible es un mapa { la, en, … }, con el latín siempre disponible. La liturgia es una resolución: el temporal (tiempos litúrgicos a partir de Pascua) y el santoral (fiestas fijas) proponen cada uno un oficio; la precedencia (ocurrencia dentro del día, concurrencia en sus límites) elige el que prevalece y el destino de los demás; el oficio elegido proporciona Misa y Oficio, ensamblados Propio → Común → Salterio.

Rutas

Regla de ubicación. Los recursos comunes a los ritos están en el nivel superior (/calendars, /saints, /regions); los propios de un rito se ubican bajo /calendars/{cal}. Un día devuelve un resumen ligero; las capas grandes pueden incluirse mediante ?include= (para lotes) o como subrecursos con dirección propia (para enlaces directos). Ambas opciones existen (véase Inclusiones).

Inclusiones. ?include=masses,office,resolution,martyrology incorpora esas capas grandes en línea en un día (o cada día de un intervalo/año), de modo que la vista habitual de lecturas mensuales requiere una llamada, en lugar de 1 + N. Las URL de subrecursos (…/masses, …/office/{hour}, …/resolution) se conservan para enlaces directos. Sin include, el día solo contiene el resumen y links.

Las colecciones (/days?from..to, /years/{label}, ambas búsquedas /saints) devuelven una envoltura, nunca un array sin más, para mostrar la consulta, los totales, la paginación y los límites aplicados: la respuesta incluye esos datos.

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

Los arrays dentro de un recurso, como saints.* y readings, son subcampos acotados, no colecciones; se mantienen sin envoltura.

Identificadores y negociación.

• Fechas: un día concreto usa ISO completo YYYY-MM-DD; una fiesta fija recurrente usa MM-DD; una fiesta móvil usa un objeto anchor (§2). Un año litúrgico tiene identidad propia; el {label} canónico es el intervalo de Adviento a Adviento YYYY-YYYY (p. ej., 2025-2026), evitando la ambigüedad de un solo año entre inicio y final. Un YYYY aislado (el año que comienza en Adviento de YYYY) o una fecha comprendida en él redirige con 301 al intervalo canónico, así que un año equivale a una URL.
• region es una precisión opcional de la consulta (no un segmento de ruta, por ser opcional): omitida o desconocida → general (la editio typica), con tolerancia (nunca error), reflejada con region_default_applied. En cambio, {cal} es un segmento estructural, y un cal incorrecto devuelve 404.
• Los identificadores de ruta no distinguen mayúsculas. {cal} (ordinary/traditional/dominican, sin alias), {hour} y {mass} se resuelven con cualquier capitalización (Traditional, Vespers, MIDNIGHT funcionan); un identificador desconocido sigue devolviendo 404. Esta tolerancia facilita el uso.
• El idioma se selecciona con Accept-Language (negociación de contenido), sin ruta ni parámetro. El latín siempre está disponible, así que la selección solo añade y nunca se devuelve 406. Las respuestas envían Vary: Accept-Language.
• La traducción es un segundo eje, distinto del idioma: dentro de un idioma existen varias ediciones bíblicas (en: douay, cpdv; la: vulgate [Clementina], con la Nova Vulgata prevista), y el usuario puede preferir una. Se selecciona con el parámetro opcional de consulta translations; editions= es el nombre canónico (coincide con el campo de respuesta), y translations= se admite como alias. Es una lista de ids de edición separados por comas (editions=cpdv,vulgate), como máximo uno por idioma, aplicada solo al text de las lecturas (las referencias y los textos no bíblicos no dependen de la traducción). Desconocida o ausente → edición predeterminada del idioma, con tolerancia (nunca error), reflejada mediante editions (y un elemento warnings en colecciones cuando se usa la edición predeterminada). Cada text de lectura resuelto lleva la edition que lo produjo, para que la respuesta no sea ambigua. /liturgy/v1/translations enumera las ediciones por idioma; la selección interviene en Vary y ETag (abajo). Por qué un parámetro y no Accept-Language: la etiqueta HTTP selecciona un idioma, no una edición editorial dentro de él; sobrecargarla (en-x-cpdv) no es estándar y las CDN que reconocen idiomas no pueden almacenarla correctamente.
• Los identificadores de santos tienen dos espacios de nombres: id propio del rito y person canónico, así que los vínculos cruzados son obligatorios: un registro del rito lleva person (enlace superior), y el calendars{} de una persona lleva ref (enlace inferior). Ningún id queda sin salida.

Caché. Una respuesta es una función pura de (cal, date, region, Accept-Language, translations, data-version). ETag incorpora los seis, además de la ruta, de modo que una CDN basada en ruta y Vary no devuelve la variante equivocada de región, idioma o traducción. Una corrección de datos o una nueva tabla regional incrementa data-version y cambia cada ETag afectado (el mecanismo de invalidación para días pasados, almacenados mucho tiempo pero nunca immutable). If-None-Match → 304.

Versiones y ciclo de vida. /liturgy/v1 es aditiva dentro de la versión principal: pueden añadirse campos (se añadirán las estructuras de cuestiones abiertas), nunca eliminarse ni cambiar de tipo. Las ediciones y regiones nuevas llegan como datos (§2), no versiones. Un cambio incompatible se publica como /liturgy/v2; después se anuncia la fecha de retirada de la versión anterior mediante cabeceras Deprecation y Sunset (al menos 12 meses de aviso), y los campos obsoletos llevan un enlace Deprecation en la documentación. Nada de v1 cambia sin aviso.

Los errores usan application/problem+json (RFC 9457) con URI type estable para máquinas, title, status, detail e instance:

• 400: entrada mal formada (fecha sin formato canónico YYYY-MM-DD con ceros, valor include fuera del conjunto permitido).
• 404: {cal}, {person}, {id} desconocido, o {hour}/{mass} no disponible ese día.
• 405: verbo distinto de GET en una ruta válida (la API es de solo lectura); incluye cabecera Allow: GET.
• 406: nunca se devuelve: el latín siempre está disponible y cualquier Accept-Language puede satisfacerse.
• 422: solicitud bien formada que la edición no puede atender (fecha fuera de su intervalo admitido).
• 429: límite de solicitudes superado, con Retry-After.
• Una region incorrecta, una edición translations desconocida o un intervalo from/to excesivo nunca producen un error: se aplica el valor predeterminado o el límite, indicando el valor aplicado (region_default_applied / editions) y un elemento warnings en las colecciones.

Convenciones.

• Tipo de contenido application/json; el contrato canónico para máquinas es el documento publicado OpenAPI 3.1 (/liturgy/v1/openapi.json), del que se generan los clientes y que constituye la autoridad para cada estructura esbozada aquí.
• Solo lectura e idempotente. Todas las rutas usan GET (por tanto, seguras, idempotentes y almacenables en caché); no hay escrituras ni se requieren claves de idempotencia.
• Autenticación y límites. Las solicitudes llevan una clave API bearer (Authorization: Bearer gianna_…), creada en la aplicación por cualquier cuenta (POST /api/keys, mostrada una vez; gestión y revocación mediante GET/DELETE /api/keys). También sirve una sesión de navegador iniciada para uso interno. Estos datos son gratuitos: requieren cuenta, sin plan. Sin autenticación → 401 (con WWW-Authenticate: Bearer); sesión anónima de visitante → 403. El índice del servicio, openapi.json y las fuentes feasts.ics son públicos y no necesitan clave. Los límites se aplican por hogar en ventanas fijas, mediante 429 y Retry-After (y RateLimit-Limit en el 429); el proxy inverso limita las IP en primera instancia. La autenticación y el nivel no modifican la representación, por lo que no intervienen en la clave de caché.
• Cabeceras de caché. Cada respuesta tiene ETag con Cache-Control: public, max-age=… acotado y stale-while-revalidate. Las fechas pasadas reciben un max-age largo (la respuesta rubricística es estable), pero no se marcan immutable: una corrección o una nueva tabla de region puede cambiar incluso una resolución histórica, y immutable fijaría para siempre la copia desactualizada. ETag (basado en versión de datos, región e idiomas) es el mecanismo de invalidación; los clientes revalidan con If-None-Match. Las respuestas son public porque su representación no depende de quien solicita; pero la API requiere acceso, por lo que una caché periférica del operador debe exigir la clave bearer antes de servir desde la caché (no pongas una caché compartida anónima delante de /liturgy/v1).
• «Hoy». No existe un recurso «hoy» en el servidor: el día litúrgico sigue la fecha civil de quien solicita, que un servidor UTC no debe decidir. El cliente resuelve su fecha local y la pide explícitamente (…/days/2026-06-09). Accept-Language/region nunca implican una fecha.
• Control de coste de ?include. Se rechaza (400) include en colecciones de varios días para las capas grandes (office, masses) que superen un intervalo corto (p. ej., > 31 días), evitando respuestas desmesuradas de un año; usa los subrecursos diarios. resolution (ligero) se puede incluir siempre.

1. Calendarios (ritos)

Un sistema autónomo, con santoral, precedencia, propios y edición propios. Una fecha se resuelve independientemente en cada uno, por lo que la precedencia es por rito (§4), no global.

Cada uno tiene un id estable (ordinary, traditional, dominican, sin alias) e indica si ofrece un Oficio.

Nota: una nomenclatura en todo el producto. Estas tres palabras son los nombres de todo el producto: la preferencia de calendario del hogar guardada, la ruta de la aplicación /api/prefs, la herramienta litúrgica del agente y el texto visible usan exactamente ordinary / traditional / dominican. Los anteriores ids y alias (roman-ordinary, roman-1962, general, of, tlm, op) se retiraron mediante un cambio incompatible antes de que la API tuviera consumidores externos: aquí devuelven 404, la ruta de preferencias los rechaza y la migración 0029 actualizó las filas guardadas. Los sinónimos humanos («TLM», «Misa en latín», «forma extraordinaria», «Novus Ordo») son lenguaje natural: el modelo los convierte a la palabra canónica; los analizadores solo aceptan las tres, sin distinguir mayúsculas.

2. Entradas de resolución: rito, año, región

Temporal: móvil, anclado en Pascua (→ Septuagésima, Miércoles de Ceniza, Ascensión, Pentecostés, numeración de domingos; Adviento ancla el otro extremo). Es función del año.

Nota: la Pascua se calcula. Mediante el cómputo gregoriano occidental; todas las fechas móviles dependen de él, por lo que se fija a un algoritmo con nombre y una tabla de regresión de fechas conocidas. El cómputo oriental juliano y los cálculos históricos divergentes quedan fuera del alcance.

Santoral: tres tipos:

• fijo: mes y día, independiente del año (Navidad, 25 de diciembre). La mayoría.
• móvil: anclado al temporal mediante una regla (Sagrada Familia = domingo en la octava de Navidad o 30 de diciembre; Sagrado Corazón = viernes tras la octava de Corpus Christi). Lleva anchor.
• móvil, distinto por rito: la regla de anclaje cambia (Cristo Rey = último domingo antes de Adviento en la forma ordinaria, último de octubre en 1962). El ancla es propiedad de (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: las ediciones usan capas de diferencias internas; se publican resultados combinados. Una versión es una tabla base más capas de reformas (1568 → … → 1960), una técnica de construcción interna. No hay selector de año de rúbricas (no se puede pedir «1939»); la selección de edición queda para el futuro (Límites).

Región: tres efectos rubricísticos, dos modelados: qué fiestas se trasladan al domingo (por conferencia: Epifanía/Ascensión/Corpus Christi) y cuáles son de precepto (§3a). También aporta fiestas propias (patronos), no modeladas (Límites).

Nota: la región representa menos que la función real de una conferencia. Sus fiestas propias sí afectan la precedencia (una solemnidad patronal cambia el día), pero solo modelamos traslado y precepto. El valor general representa la editio typica: mantiene Ascensión, Epifanía y Corpus Christi entre semana, aunque gran parte del mundo los celebra en domingo. Consultar traslado y precepto con el valor predeterminado da la respuesta de la edición típica, sin adaptar al país. Las tablas de conferencias son datos que se añaden con el tiempo.

Año litúrgico: empieza el primer domingo de Adviento (un año civil abarca dos); los ciclos de la forma ordinaria dependen de él:

"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: los dos ciclos cambian en fechas diferentes. El dominical cambia en Adviento; el semanal (I = años civiles impares) el 1 de enero, a mitad del año litúrgico. Un starts no permite derivar ambos, por lo que se ofrecen resueltos. Los ciclos son null en 1962 (anual). psalter_week es null también fuera de 1962: solemnidades y fiestas usan la semana I, y las octavas y los últimos días de Adviento/Semana Santa sustituyen el salterio. Es una orientación para días ordinarios, nunca un valor general de 1 a 4.

3. El día litúrgico

La ruta diaria devuelve el resumen (núcleo ligero y enlaces); el Oficio, propios completos de Misa y resolución se piden por separado (tabla superior). El resumen:

{
  "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: saints mantiene listas separadas. celebrated/commemorated son los resultados litúrgicos de ESTE calendario (una feria no es un santo y nunca aparece). associated es el índice de santos de fecha fija del calendario seleccionado, para que la precedencia no borre la asociación a una fiesta. remembered es el Martirologio romano: TODOS los santos de la fecha (a menudo entre 5 y 15), celebrados o no (edición de 1916 de dominio público incluida; faltan los canonizados después, aunque la capa de calendario los incluye; sus fechas siguen el calendario antiguo cuando difieren). Los resultados de resolución futuros (transferred, omitted) llegarán como claves nuevas añadidas. remembered[].name solo está en inglés (Límites). Siempre hay nombres; el elogio note de cada entrada se incorpora con ?include=martyrology (inclusión grande, con intervalo limitado como masses/office; los elogios de 90 días ocuparían la mayor parte de la respuesta). Las respuestas se comprimen con gzip cuando se negocia.

Nota: el resumen enumera descriptores de Misas. masses[] lleva el ligero { id, name, colour, option_type } por Misa (los propios llegan con masses_url o ?include=masses). Una simple cantidad exigiría otra llamada para conocer las Misas; además, celebration.colour es el color del día, que puede diferir en un día con varias Misas, cada una con su color (un Réquiem usa negro mientras el día indica blanco, §7). El colour por Misa es aquí la autoridad para representar una celda diaria.

Nota: la fecha civil es la clave; dos hechos distintos en la tarde del sábado. (Abierto.) Usamos la fecha civil (otra clave haría ambigua la solicitud de 2026-06-09) y modelamos la prolongación vespertina con relaciones explícitas separadas: primeras Vísperas (rúbricas: el Oficio del día siguiente se reza esta tarde; liturgical_evening.belongs_to) y Misa anticipada (derecho canónico: una Misa del sábado por la tarde cumple el precepto dominical; anticipated_mass). El Oficio puede ser el de mañana mientras la Misa sigue siendo la de hoy. Abierto: su estructura exacta.

3a. Precepto: depende de la región y no puede derivarse del rango.

"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: tres estados y referencia para máquinas. Un booleano no expresa la regla de precepto parcial (cesa en sábado/lunes) sin cambiar entre años; reason_code es el identificador programático junto al texto. En general (edición típica), la respuesta es la ley universal: cada domingo y las diez fiestas del canon 1246 (ocho fijas y las móviles Ascensión/Corpus Christi), con reason indicando cuál. No se deriva del rango: la mayoría de las solemnidades no tienen precepto. La supresión/traslado regional (reason_code, lapsed) se completa con las tablas regionales.

Celebración

{
  "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: el identificador textual depende del rito; person enlaza al registro común. Un santo puede variar de rango, nombre e incluso fecha según el rito; id identifica la celebración de este rito, y person es el enlace obligatorio al registro canónico común (§11), cuyo calendars{} enlaza de vuelta. Los dos espacios de nombres no se confunden porque cada id se empareja siempre con el otro.

4. Rango, precedencia, resolución

La parte más codificada. Dos cuestiones: ocurrencia (dos oficios en la misma fecha: quién es celebrado, conmemorado, omitido o trasladado) y concurrencia (las segundas Vísperas de un oficio coinciden con las primeras del siguiente: a quién pertenecen; §8).

Los grados varían por rito. 1962/dominicano: cuatro clases I–IV, conmemoraciones y feria; la clase de fiesta y la de día (domingo, feria, vigilia, día de octava) se intercalan (una feria de clase I prevalece sobre una fiesta de clase I; un domingo de clase II prevalece sobre una fiesta de clase III, que se conmemora). Forma ordinaria: solemnidad > fiesta > memoria > memoria libre > día de semana (tabla de 1969).

Nota: el domingo tiene varios rangos. En 1962: domingos de clase I (Adviento/Cuaresma/Tiempo de Pasión, casi no admiten nada) y clase II (domingos verdes que una fiesta de clase II puede desplazar). La forma ordinaria tiene un paralelo: los domingos de Adviento/Cuaresma/Pascua prevalecen sobre toda fiesta; los ordinarios ceden a fiestas del Señor. El rango del domingo indica su clase concreta, nunca un único nivel.

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

Notas sobre rank.

• cycle = ciclo que propone: un domingo/feria es temporale, aunque sea clase de día y no fiesta (esa distinción está en label).
• precedence solo compara dentro de una resolución (un rito, un día); comparar entre ritos no tiene sentido, pues nunca se resuelve una fiesta de 1962 frente a una de la forma ordinaria (§1).
• precedence ordena; no decide. (Abierto.) Parte de la precedencia es condicional (una fiesta del Señor desplaza un domingo ordinario, pero no uno de Adviento/Cuaresma/Pascua), algo que dos enteros no pueden decidir; el motor usa la tabla completa y el entero es solo el resultado. Abierto: ¿mostrar la regla o solo su resultado?
• El día no tiene un rango escalar único: Misa, horas diurnas y ambas Vísperas pueden resolverse a oficios distintos por concurrencia, consultables por separado (§7/§8).

Resolución (opcional): la decisión completa:

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

Traslado. Una fiesta impedida de rango suficiente se mueve al siguiente día libre, y otra vez si está ocupado (una cadena: final de Adviento, octava de Navidad, Semana Santa); si no hay ninguno antes de una fecha límite, no se celebra ese año. Una fiesta puede así llegar de una fecha anterior (transferred_from/transferred_to), indicada en los registros saints de la nueva fecha mediante from (§6). outcome distingue transferred (trasladada fuera), not-observed y omitted (permanece, sin rezarse nada).

Nota: los domingos retomados son un movimiento distinto. (Abierto.) Un domingo impedido después de Epifanía/Pentecostés puede retomarse semanas después, antes de Adviento; se parece a un traslado, pero no es una fiesta, por lo que la cadena no encaja. No está modelado: aparece solo en su fecha de celebración, sin enlace de vuelta. Abierto: una relación resumes:.

5. Tiempos litúrgicos y color

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

Ids: advent · christmas · (1962:) epiphany · septuagesima · passiontide · pentecost (periodo after-pentecost) · (ambos:) lent · easter · (forma ordinaria:) ordinary. El tiempo de Ascensión está dentro de easter; el tiempo después de Pentecostés de 1962 usa pentecost y arc, sin id separado. Las semanas empiezan en 1 y se anclan al domingo (la semana de un periodo que comienza entre semana, como Ceniza o los días tras Epifanía, es la semana 1). La Navidad de la forma ordinaria llega hasta la víspera del Bautismo; en 1962 el tiempo de Navidad cede al de Epifanía el 6 de enero. Los tiempos determinan el color, los cambios de cantos de Misa (§7), si se rezan Gloria/Aleluya/Te Deum y la selección de feria o Común.

Nota: qué cuenta week. No es un contador global. 1962 reinicia por periodo: after-epiphany y after-pentecost comienzan en 1 (arc los distingue); la numeración tras Pentecostés varía de 23 a 28 cada año, y los últimos domingos tras Epifanía se retoman antes de Adviento (§4). En la forma ordinaria, el tiempo ordinario tiene una numeración 1–34 que salta Cuaresma y Pascua (…8, [Cuaresma/Pascua], 11…); arc es null.

Nota: season es la posición celebrada, escalar por decisión. Un día puede estar en dos marcos (un día de la octava navideña es christmas y miembro de octava; un domingo retomado está en su lugar previo a Adviento, aunque proceda de después de Epifanía). Un objeto para la posición celebrada, con octava separada (§9); se pierde el marco original del domingo retomado (abierto, §4). Es infrecuente.

Nota: el color es { default, alternatives[] }, nunca escalar. Gaudete/Laetare añaden rosa; un Réquiem usa negro o violeta; algunas vigilias y votivas difieren. Valores: blanco, rojo, verde, violeta, rosa, negro, dorado.

6. Conmemoraciones y bloque saints

Un oficio inferior impedido se conserva como fragmento de oraciones en el oficio que prevalece, sin constituir otra Misa.

• Composición: Misa: segunda o tercera Colecta, Secreta, Poscomunión. Laudes/Vísperas: antífona, versículo y colecta. Maitines: a veces una novena lección.
• Dos grados: privileged (domingos, fiestas de clase I, ferias de Adviento/Cuaresma, Témporas, días de la octava de Navidad, Letanías Mayores: Laudes, Vísperas, todas las Misas) y ordinary (Laudes/Vísperas y solo Misas rezadas; omitidas en Misa solemne).
• Orden y límite: ordenadas (primero las privilegiadas; primero la clase superior; orden fijo dentro de clase), recortadas por regla según el límite de oraciones (el recorte aporta información).
• Días que no admiten ninguna: Domingo de Ramos, Vigilia de Pentecostés, días de mayor rango: vacío por regla (con motivo) ≠ ninguna corresponde hoy (ausencia).

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

Nota: el límite se calcula; las colectas imperadas se separan. El límite se calcula por día y tiempo litúrgico, sin una constante de 3. Una colecta imperada (añadida por el obispo o las rúbricas) no conmemora a un santo: usa el campo propio imperated_collects[] de la Misa.

Nota: el Último Evangelio está incluido; el Prefacio queda fuera. Cuando una fiesta desplaza un domingo (1962), el Evangelio del domingo conmemorado se convierte en Último Evangelio propio, seleccionado por calendario e incluido (last_gospel). El Prefacio del día depende del rango y tiempo, pero pertenece al Ordinario, un límite (como máximo se ofrece una etiqueta, sin texto).

saints: de quién es la fiesta. Una conmemoración corresponde al oficio que cede en un conflicto de precedencia; el santo principal nunca está en saints.commemorated, y un oficio que cede no siempre se conmemora:

El bloque usa el resultado como clave en lugar de una lista plana marcada, por lo que la pregunta habitual («¿quién se celebra hoy?») requiere acceder a una sola clave y los nuevos resultados amplían la estructura sin romperla. remembered del Martirologio queda junto a ellas como tercer nivel: la conmemoración completa de la Iglesia para la fecha, fuera de los resultados de resolución.

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

7. Misa

Los propios, frente al Ordinario fijo, ordenados: Introito · Colecta · Epístola · Gradual/Tracto/Aleluya · [Secuencia] · Evangelio · Ofertorio · Secreta · Comunión · Poscomunión. Varios son lecturas bíblicas (forma ordinaria: primera/segunda y salmo; tradicional: epístola/evangelio); los textos cantados (Introito, Gradual, Ofertorio, Comunión) son antífonas propias. Cada posición indica su función, de modo que una estructura sirve para todos los ritos:

{ "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: la traducción es un eje por texto, independiente del idioma (§10). Solo lo lleva el text bíblico; ref, nombres, rúbricas y antífonas cantadas no. edition indica la traducción usada por idioma (tras solicitar translations y aplicar el valor predeterminado por idioma), para que el cliente sepa si pidió una y recibió otra por no estar disponible para ese pasaje. Todas las ediciones ofrecidas son de dominio público y se almacenan internamente.

Nota: readings[] tiene longitud variable y orden, sin plantilla fija de Epístola/Evangelio: un sábado de Témporas tiene hasta seis lecciones; la Vigilia Pascual, una serie de profecías (12 antiguamente / 4 en 1962); varias entradas role: "lectio" se distinguen por posición.

Nota: canto entre lecturas y Secuencia. La posición entre lecturas es una función (interlection) que varía según el tiempo: Gradual / Tracto (penitencial) / doble Aleluya (Pascua). La Secuencia es una posición separada después del Aleluya: role: "sequence", obligation: obligatory | optional (obligatoria en Pascua/Pentecostés; Lauda Sion/ Stabat Mater opcionales; Dies Irae ligada al Réquiem).

Una fecha, varias Misas: masses es una lista (una Misa = lista de un elemento):

• multiplicidad prescrita: las tres de Navidad (Medianoche/Aurora/Día), las grandes vigilias; se celebran todas.
• opción libre: memoria libre o feria en la forma ordinaria; se celebra una.
• Réquiem prescrito: cuando el día es Réquiem (Fieles Difuntos = tres), incluido; las votivas discrecionales y Réquiem ocasionales quedan fuera (Límites).

"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. Oficio (Oficio Divino / Liturgia de las Horas)

Ocho horas: matins · lauds · prime · terce · sext · none · vespers · compline (Prima suprimida en la forma ordinaria; cada calendario anuncia sus horas). Cada una: salmos/ cánticos enmarcados por antífonas; himno; capítulo, versículo y responsorio; colecta. Cánticos evangélicos por hora: Benedictus (Laudes), Magnificat (Vísperas), Nunc Dimittis (Completas). Maitines es mayor: uno o tres nocturnos de salmos y lecciones, Te Deum en días festivos.

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

Ensamblado por capas: Propio → Común o Comunes aplicables → Salterio, con selección independiente para cada elemento (colecta del Propio, salmos del Salterio, etc.).

Nota: la capa del Común es compuesta. titles es un conjunto (["martyr","bishop"] → se combinan ambos Comunes), y cada Común tiene varios formularios por tiempo litúrgico: resolver entre los Comunes aplicables y elegir el formulario correcto del tiempo, sin una correspondencia de título único a Común único.

Primeras y segundas Vísperas (concurrencia): una fiesta tiene primeras Vísperas la víspera y segundas Vísperas el propio día; cuando coinciden, la precedencia (§4) decide cuáles se cantan y si se conmemoran las otras. «Vísperas del día D» es ambiguo; ambas son objetos distintos.

Nota: las Vísperas de origen combinado quedan fuera. La concurrencia no siempre es un cambio íntegro: salmos de un oficio y capítulo/himno/colecta a capitulo de otro, unas Vísperas de dos oficios que Propio→Común→Salterio no puede expresar. Ofrecemos las Vísperas resueltas y el resultado, sin desglosar los elementos.

9. Octavas, vigilias y días de tiempos privilegiados

Octavas: fiesta de primer rango prolongada ocho días; cada día infra octavam y el dies octava tiene su rango y puede ser impedido. En 1960 se conservan tres (Navidad, Pascua, Pentecostés). octave: { of, day }: day es la posición; la clase real está en rank (los días de octava navideña no son uniformes: 26–28 de diciembre, clase III; día de la Octava, clase II).

Nota: el tipo de octava queda fuera desde 1960. Antes de 1955 se clasificaban en privilegiadas, comunes y simples; en 1960 quedaron tres, así que hoy no hay type. Una edición anterior a 1955 (§2) necesitaría octave_type.

Vigilias: víspera litúrgica de una fiesta importante, día separado en la fecha anterior con su propia Misa y oficio; puede caer dentro de otra octava.

Nota: las vigilias tienen tipo. vigil_type: ordinary (conmemorada si queda impedida) | privileged (Nochebuena, prevalece sobre un domingo) | paschal (Vigilia Pascual, inicio del Triduo). El rango es propiedad del día (rank).

Días del temporal de tiempos privilegiados: tipos de día con Misas propias, rango y conmemoración privilegiada (rank.cycle: "temporale"), más allá de ferias comunes: ferias de Adviento desde el 17 de diciembre (días de las «O»); propios de los días de Cuaresma; Témporas (Quattuor Tempora); Rogativas (Letanía Mayor, 25 de abril, y Letanías Menores), procession: true.

Nota: el texto de la letanía procesional no se ofrece. La Letanía de los Santos en procesión no es propio de Misa ni hora del Oficio; es un cuarto tipo de contenido sin ubicación en §7/§8. Día, Misa y rango sí se incluyen; procession: true lo indica; el texto de letanía queda fuera.

10. Texto multilingüe

Cada texto legible es un mapa de idiomas { "la": …, "en": …, "fr": … }:

• Siempre hay latín: presente, de dominio público y nunca excluido por filtros.
• Los idiomas son datos, no esquema: añadir fr/es añade una clave; la solicitud puede reducir los idiomas conservando siempre el latín.
• Referencia ≠ texto: ref es un dato independiente; text es su representación traducible, que puede faltar.

Idioma y traducción: dos ejes. El idioma (Accept-Language) elige la clave del mapa; la traducción (parámetro translations) elige, solo para text bíblico, qué edición de dominio público ocupa esa clave. Se combinan: Accept-Language: en y translations=cpdv → texto inglés de CPDV. Las ediciones también son datos (por idioma: en → douay | cpdv; la → vulgate), cada idioma con una predeterminada; la elección resuelta aparece en cada lectura mediante edition (§7) y se indica en la respuesta mediante editions. Los textos no bíblicos (nombres, rúbricas, antífonas cantadas) tienen una representación canónica por idioma e ignoran ese eje. Todas las ediciones se almacenan internamente (colecciones de dominio público incluidas en el servicio); ninguna se obtiene de terceros.

11. Santos

Dos niveles. Una entrada propia de un rito (§3) es la celebración de ese rito, con su fecha, rango y nombre. Por encima está una persona canónica que identifica al mismo santo entre ritos, para consultar todos los calendarios juntos, incluso cuando mantienen fechas distintas (Catalina de Siena: forma ordinaria, 29 de abril; 1962, 30 de abril; Efrén: forma ordinaria, 9 de junio; 1962, 18 de junio). La persona es un índice, conservando los datos propios de cada rito. La unificación usa normalización de nombres (elimina tratamientos y títulos, combina variantes ortográficas), una lista pequeña de alias verificados e identificadores distintos por rito cuando un nombre normalizado ya está ocupado. Las fechas no se usan como claves de identidad porque una reforma puede mover la fiesta del mismo santo.

Persona: todos los calendarios juntos (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" }
  }
}

Cada bloque de rito lleva su id local y un ref (enlace descendente); la entrada propia del rito lleva person (enlace ascendente, §3). Ninguno de los dos espacios de identificadores deja al cliente sin salida.

La búsqueda distingue los varios santos llamados Juan; el nombre solo puede coincidir, así que cada uno lleva títulos y fechas de fiesta. La búsqueda global muestra los calendarios que conservan a cada uno; la del rito enumera solo su santoral. Los resultados usan la envoltura de colección (Rutas), con Accept-Language para el texto:

// 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 resultado por persona, con feasts[] indicando cada celebración (un santo puede tener varias: Natividad y Decapitación, un día de octava, una fiesta secundo §6). date es MM-DD (fija) o un anchor móvil (§2).
• La coincidencia se busca entre nombres de idiomas, sin distinguir diacríticos y con latín siempre presente. q busca el nombre; title / month son filtros separados.
• La búsqueda por rito (/calendars/{cal}/saints) devuelve identificadores locales y solo fecha, rango y títulos de ese rito; un santo ausente del rito no aparece en sus resultados.

Límites (no ofrecido)

• Canto y ceremonial, y el Ordinario fijo de la Misa; ofrecemos el propio y el calendario que lo selecciona.
• Primeras Vísperas (…/office/first-vespers): dependen de la resolución de concurrencia, aún no calculada; la ruta devuelve 404 antes que ofrecer las segundas Vísperas con el nombre incorrecto. vespers/second-vespers (las propias del día) sí se ofrecen.
• Los nombres de santos están solo en inglés por ahora: el santoral incluido no contiene nombres latinos, así que los bloques name de santos son { en } (única excepción al latín siempre presente, que se mantiene para todo texto litúrgico); el latín se completará al indexar los datos del rito.
• El Prefacio (Ordinario); el Último Evangelio del domingo conmemorado (propio) sí se ofrece (§6).
• Texto de letanía procesional (Rogativas/Letanía Mayor, §9); el día sí está incluido.
• Vísperas de concurrencia con origen combinado (§8): se ofrecen las resueltas, sin desglose.
• Misas votivas discrecionales y funerales/nupciales ocasionales (los días de Réquiem prescritos sí están, §7).
• Calendarios locales/propios fuera de los tres ritos, tablas de traslado/precepto por conferencia y fiestas propias regionales (patronos, que sí afectan la precedencia); datos que llegarán con el tiempo (§2).
• Ediciones históricas arbitrarias: solo las tres combinadas; sin selector de año de rúbricas (un eje edition queda para el futuro, §2).
• Dos marcos de tiempo litúrgico simultáneos (origen de un domingo retomado, §5).
• Cómputo oriental juliano: se supone la Pascua gregoriana (§2).
• Títulos vernáculos de días del temporal: el latín siempre está disponible; el nombre inglés es una capa añadida hasta donde permiten las fuentes (Divinum Officium conserva los títulos del temporal y fiestas del Señor en latín), por lo que aproximadamente un tercio de los días de 1962/dominicanos no tiene nombre inglés (lecturas y Oficio sí están traducidos donde existe una versión libre). Las fiestas del santoral reciben el nombre inglés cuando la fuente lo incluye.
• Cálculo de traslados/omisiones (§4/§6): el motor resuelve la ocurrencia (prevaleciente y conmemoraciones), pero aún no el mecanismo de traslados. saints.associated conserva las asociaciones de fecha fija de la forma ordinaria de modo independiente; resolution.displaced aún contiene solo commemorated. Los resultados omitted / transferred / not-observed y chain figuran en la estructura y se completarán al implementar los traslados (las tablas DO Tabulae/Transfer están incluidas para ello). Indicamos ausencia antes que un traslado supuesto.

Cuestiones abiertas

• Día litúrgico frente a fecha civil como clave (§3): estructura de las relaciones de prolongación vespertina.
• Precedencia condicional (§4): ¿mostrar la regla o solo el resultado?
• Domingos retomados (§4): relación resumes: distinta del traslado.

Fuentes

Rangos de días litúrgicos · Conmemoración · Ocurrencia · Propio · Breviario romano · Calendario romano general de 1960 · Rúbricas generales de 1960 · romcal (antecedente del modelo de calendario).

Procedencia de datos (almacenados internamente, sin llamadas a terceros durante la ejecución). Calendario, propios y Oficio: colección Divinum Officium de dominio público incluida. Martirologio: edición de Baltimore de 1916, de dominio público, incluida (data/martyrology/). Escritura: ediciones de dominio público incluidas; la: Vulgata Clementina (y Nova Vulgata donde es libre); en: Douay-Rheims (Challoner), Catholic Public Domain Version. Las referencias son datos sin derechos de autor. Nada se obtiene de un servicio externo al realizar una solicitud.