Skip to content

Source data

Jump to bottom
John R. D'Orazio edited this page Dec 28, 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 jsondata/ 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 jsondata/ 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.

Latin editions of the Roman Missal

The primary source for the Universal Roman Calendar is the Roman Missal, specifically the Latin editions of the Roman Missal. The primary reference for calculations are the Universal Norms on the Liturgical Year and the Calendar which accompanied the Motu Proprio Mysterii Paschalis issued by Pope Paul VI and which are both published in the Roman Missal itself after the Institutio Generalis Missalis Romani ("General Instruction of the Roman Missal").

Proprium de Tempore

The liturgical data (Grade, Color etc.) for all mobile festivities are defined in the jsondata/sourcedata/missals/propriumdetempore/propriumdetempore.json file while the corresponding mobile dates are calculated within the API itself, as they mostly depend on the calculation of the date of Easter. Also the dates for Christmas and liturgical events that depend on Christmas, for Feasts and Solemnities of the Lord, basically anything that is from the Proprium de Tempore rather than from the Sanctorale, are calculated within the main API itself. The API associates a unique event_key with each liturgical event. Translatable liturgical data (such as liturgical grade, liturgical commons, liturgical colors) is defined in the PHP code of the API (mostly in src/Enums/*.php) and handled via system gettext calls; these kinds of translations therefore do not use JSON resource files but rather .mo and .po files.

  • The display names in Latin for liturgical events from the Proprium de Tempore are defined in the jsondata/sourcedata/missals/propriumdetempore/i18n/la.json resource. This translatable resource simply contains key/value pairs, where the key is the event_key defined for the liturgical event in jsondata/sourcedata/missals/propriumdetempore/propriumdetempore.json. 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 jsondata/sourcedata/missals/propriumdetempore/i18n/ folder follow the pattern {locale}.json where locale is the lowercase ISO 639-2 Alpha-2 language code for the translation; these files are handled by the above mentioned Weblate translation server. Since these translations are for the General Roman Calendar and not for any particular nations, there is no national extension on the language codes.

Sanctorale

The liturgical data for the Sanctorale from the various Latin editions of the Roman Missal can be found in the folders jsondata/sourcedata/missals/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 within the folder, i.e. jsondata/sourcedata/missals/propriumdesanctis_{YEAR}/propriumdesanctis_{YEAR}.json.

  • The jsondata/sourcedata/missals/propriumdesanctis_{YEAR}/propriumdesanctis_{YEAR}.json file does not contain the display name of the liturgical event, but only an event_key property 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 jsondata/sourcedata/missals/propriumdesanctis_{YEAR}/i18n/.

  • The files within the jsondata/sourcedata/missals/propriumdesanctis_{YEAR}/i18n/ subfolder follow the pattern {locale}.json where locale is the lowercase 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 jsondata/sourcedata/decrees/ folder, where a resource file in JSON format of the same name resides, i.e. jsondata/sourcedata/decrees/decrees.json

  • The jsondata/sourcedata/decrees/decrees.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 event_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 jsondata/sourcedata/decrees/i18n/ subfolder following the same pattern {locale}.json and are again handled in the liturgical-calendar project of the Weblate translation server.

Wider Regions

Some liturgical events apply to more than one region or nation, perhaps to an entire continent. For example, the Patron saints of a wider region, such as Europe or the Americas or Asia, which are applicable to the various regional editions of the Roman Missal within the same "wider region". Seeing that this data is often associated with a Decree from the Congregation for Divine Worship or an Apostolic Letter, and applies to multiple language editions of the Roman Missal in various regions within the same wider region, we opted to place this data not in the jsondata/sourcedata/decrees folder but in a jsondata/sourcedata/calendars/wider_regions/ folder.

  • The liturgical data for each liturgical event for a wider region is defined in a resource file jsondata/sourcedata/calendars/wider_regions/{Wider_region}/{Wider_region}.json, where {Wider_region} is the English capitalized name of the wider region (i.e. Europe/Europe.json, Americas/Americas.json, Asia/Asia.json). This resource simply contains the instructions on how to handle the liturgical event, which often times will already exist in the Universal Roman Calendar but will change grade and perhaps receive a slight change to the name (for example, "Saint Benedict, Patron Saint of Europe"). Or perhaps a new liturgical event could be created. Often times the declaration of the patron saint of a wider region will be associated with a Decree from the Congregation for Divine Worship or an Apostolic Letter; this resource file allows to associate the decree with the liturgical event. The instructions are found within the litcal array; the liturgical data is found under litcal[n].festivity and the instructions for handling and any related decrees are found under litcal[n].metadata. This resource file also indicates which national_calendars will inherit this data, and in which regional locales the translation data will be translated (metadata.locales).

  • The translatable data for the liturgical event can be found in the i18n/ subfolder (jsondata/sourcedata/calendars/wider_regions/{Wider_region}/i18n/{locale_REGION}.json), where locale is the lowercase ISO 639-2 Alpha-2 two letter language code and REGION is the uppercase ISO 3166-1 Alpha-2 two letter Country code, following the IETF working groups BCP 47 standard for language codes. We are using an underscore here because that is how PHP processes locale names / codes, so it was easier to handle in the main API which is written in PHP; also the Weblate translation server is able to handle this convention just fine. Other systems such as browsers and javascript will use a - dash instead of an _ underscore between the language and the region. If only there were a standard that would encourage the usage of one over the other, it would make for better interoperability... There isn't really any specific source translation file in this case; simply at least one language resource must be initially defined, and then the translation process can be incorporated into the Weblate translation server and further handled from there.

Regional / language editions of the Roman Missal

If a regional edition of the Roman Missal, for example the Roman Missal for Italy or for the United States, adds any new liturgical events to the Universal Roman Calendar, this data is defined in a jsondata/sourcedata/missals/propriumdesanctis_{REGION}_{YEAR}/ folder, where {REGION} is the uppercase ISO 3166-1 Alpha-2 two letter Country code of the nation/country/region in which the language edition of the Roman Missal was published (i.e. IT or US), and {YEAR} is the year in which the regional language edition of the Roman Missal was published.

Note

Preferring a reference to the {REGION} rather than to the language allows us to create a cascading logic in processing the data: all the dioceses in that region will inherit the data from the language edition of the Roman Missal in that region. There can be a difference in the liturgical calendar between the United States and Australia, and yet both use the same language English. So we want to define our data by region where the language edition of the Roman Missal was published. And it's not enough to identify a translation by Country code, because the actual liturgical data, the actual calendar, can be different according to the edition of the Roman Missal for each region. These affirmations need further development...

  • Within this folder is a resource file with the same name as the folder, which defines any new liturgical events that are being added to the calendar for that region: jsondata/sourcedata/missals/propriumdesanctis_{REGION}_{YEAR}/propriumdesanctis_{REGION}_{YEAR}.json. This resource file defines the event_key for each new liturgical event, and currently also defines the display name for the event, seeing that most of the time we will not need translations. However, there can be cases in which a translation in desirable, if for example there are multiple language editions of the Roman Missal within a same region. If for example in the United States there is a Spanish edition of the Roman Missal for the United States (such a Missal was in fact published in 2018), we will have to update our main API to be able to process this and allow for various language editions within the same region. In any case this resource file does not declare any particular "operations" for suppressing or moving or changing liturgical events, it simply declares new events that are not found in the language edition of the Roman Missal for the region but are not found in the Universal Roman Calendar. In any case the liturgical events defined here are all fixed date liturgical events.

  • If any operations are required to adjust the calendar for a region, such as suppressing a liturgical event or moving to a new date or changing the liturgical grade of a liturgical event, or if a movable celebration needs to be created, these operations are defined in a resource file jsondata/sourcedata/calendars/nations/{REGION}/{REGION}.json, where REGION is the uppercase ISO 3166-1 Alpha-2 two letter Country code of the region / country in which the language edition of the Roman Missal was published. If the new liturgical events for the region were already defined in the resource file associated with the edition of the Roman Missal for the region as per the previous paragraph, they needn't be created in this "operations" resource file. New liturgical events however CAN be created in this resource file. This resource file also defines any adjustments to the VATICAN calendar as regards the celebration of Epiphany, Ascension and Corpus Christi. It can also enable the celebration Jesus Christ, Eternal High Priest. It also defines any association with a Wider Region.

  • It is preferable, in order to maintain historical accuracy, to define new liturgical data for each language edition of the Roman Missal in it's own resource file jsondata/sourcedata/missals/propriumdesanctis_{REGION}_{YEAR}/propriumdesanctis_{REGION}_{YEAR}.json. However unless we have information on all language editions of the Roman Missal for a region, it may be necessary to simply define new liturgical events in the "operations" resource file jsondata/sourcedata/calendars/nations/{REGION}/{REGION}.json. For example, when defining the data for the Netherlands, I did not have access to all of the editions of the Roman Missal that have been published in the Netherlands, I simply had the Sanctorale data which was given to me by the secretary of the Vereniging voor Latijnse Liturgie. So in this case there isn't an actual resource file for a Roman Missal for the Netherlands in a jsondata/sourcedata/missals/propriumdesanctis_NL_{YEAR}/ folder, all the data is defined in the jsondata/sourcedata/calendars/nations/NL/NL.json resource file.

Diocesan calendars

Resource files for diocesan calendars are found under the jsondata/sourcedata/calendars/dioceses/ folder for the region / country whose edition of the Roman Missal they use. Since there is no new "Roman Missal" data in this case, no diocesan calendar data is to be found under the jsondata/sourcedata/missals/ folder. The resource file for each diocese is found in jsondata/sourcedata/calendars/dioceses/{REGION}/{diocese_key}/{diocese_name}.json, where {REGION} is the uppercase ISO 3166-1 Alpha-2 two letter Country code of the region or country to which the diocese belongs, and {diocese_key} is the unique key that identifies the diocese based on the jsondata/world_dioceses.json definition, and {diocese_name} is the corresponding name derived from the same jsondata/world_dioceses.json definition file (since the {diocese_key} can be a bit cryptic, we opted to keep the actual diocese name for the final JSON resource filename, to make it easier to identify the diocese). Diocesan calendar resource files generally define local memorials for local patron saints or the anniversary of the dedication of the Cathedral, and do not usually ovveride or change any data from the national liturgical calendar but simply the local data is annexed to the national liturgical calendar. A diocesan calendar resource file can however define a local ovveride for the celebration of Epiphany, Ascension and Corpus Christi seeing that there are cases in which this takes place. More often that not, diocesan calendars are in just one language, but since there can be cases where a diocesan calendar can be produced in more than one language (for example, dioceses in Canada can produce a diocesan calendar in both English and French), all possible translatable data (the name of the liturgical event) is found in the jsondata/sourcedata/calendars/dioceses/{REGION}/{diocese_key}/i18n/ subfolder for each diocese. Translation files in this subfolder follow the pattern {locale}_{REGION}.json.

Clone this wiki locally