Skip to content

Source data

Jump to bottom
John R. D'Orazio edited this page May 5, 2024 · 26 revisions

Perhaps it is useful to document how the source data is generated, stored and processed for each single calendar, whether universal, national, diocesan, or for a wider region. The source data in JSON format resides in the data/ folder of the main API repository.

The source of all local calendars is the Universal Roman Calendar. Therefore all processing for local calendars takes place in a cascading fashion, starting from the Universal Roman Calendar. There are two kinds of JSON resource files that reside within the data/ folder:

  1. Resource files that define the Liturgical data for each liturgical event or which contain instructions for creating / suppressing / moving / changing liturgical events. These resource files do not contain any "translatable" data.
  2. Resource files that contain "translatable" data (i.e. the display name for each liturgical event). The source translation file is always la.json which defines the display name in Latin for the liturgical event; all other translation files reside alongside the la.json file, and are generally handled by the Weblate translation server used for all the translations of the Calendar Data for this API.

Roman Missals

The primary source for the Universal Roman Calendar is the Roman Missal, specifically the Latin editions of the Roman Missal.

Proprium de Tempore

The dates and liturgical data (Grade, Color etc.) for all mobile festivities are defined within the API itself, as they mostly depend on the calculation of the date of Easter. Also the dates and liturgical data for Feasts and Solemnities of the Lord, basically anything that is from the Proprium de Tempore rather than from the Sanctorale, is defined within the main API itself. The API associates a unique key with each liturgical event.

  • The display names in Latin for liturgical events from the Proprium de Tempore are defined in the data/propriumdetempore/la.json resource. This translatable resource simply contains key/value pairs, where the key is that defined for the liturgical event in the main API. This separation between liturgical data and translatable display names allows us to handle translations in the Weblate translation server.
  • All other translation files within the same folder follow the pattern {LOCALE}.json where LOCALE is the ISO 639-2 Alpha-2 language code for the translation; these files are handled by the above mentioned Weblate translation server.

Sanctorale

The liturgical data for the Sanctorale from the various Latin editions of the Roman Missal can be found in the folders data/propriumdesanctis_{YEAR}/, where YEAR is the year in which a Latin edition of the Roman Missal was published. The principal source with data defining each liturgical event (such as Date, Grade, Proper / Common, liturgical color, etc.) is a file in JSON format of the same name within the folder, i.e. data/propriumdesanctis_{YEAR}/propriumdesanctis_{YEAR}.json.

  • The data/propriumdesanctis_{YEAR}/propriumdesanctis_{YEAR}.json file does not contain the display name of the liturgical event, but only a key that uniquely identifies the liturgical event. A folder structure was chosen so as to allow translation of the same data to reside within the same folder, under a subfolder /i18n.

  • The files within the data/propriumdesanctis_{YEAR}/i18n/ subfolder follow the pattern {LOCALE}.json where LOCALE is the ISO 639-2 Alpha-2 language code for the translation. The source translation file is the Latin la.json file which contains the display name in Latin for each liturgical event for the Sanctorale; all other translation files are handled in the liturgical-calendar project of the above mentioned Weblate translation server. Until now we have not needed any regional specifiers alongside the ISO 639-2 Alpha-2 language code; if however this were to become necessary in the future we will have to implement processing of such regional specific language files in the main API.

Decrees of the Congregation for Divine Worship

The second source for the Universal Roman Calendar are any decrees issued by the Congregation for Divine Worship, which establish a new liturgical event for the Universal Roman Calendar, or suppress a liturgical event, or move the event to a new date, or change the liturgical grade of an event. This data is defined in the data/memorialsFromDecrees/ folder, where a resource file in JSON format of the same name resides, i.e. data/memorialsFromDecrees/memorialsFromDecrees.json

  • The data/memorialsFromDecrees/memorialsFromDecrees.json resource file again does not define the display name of any liturgical events, it simply contains the instructions for creating, suppressing, moving or changing any liturgical events; when new liturgical events are created, the key that identifies the liturgical event will be found in this resource file.

  • The display name in Latin for any newly created liturgical event is defined in the i18n/ subfolder in the la.json resource file. Any translations for the display name in other languages also reside in the same data/memorialsFromDecrees/i18n/ subfolder following the same pattern {LOCALE}.json and are again handled in the liturgical-calendar project of the Weblate translation server.

Clone this wiki locally