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.

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.

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. Translatable liturgical data (such as liturgical grade, liturgical commons, liturgical colors) is defined in the PHP code of the API (mostly in includes/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 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 data/propriumdesanctis_{YEAR}/i18n/.

  • The files within the data/propriumdesanctis_{YEAR}/i18n/ subfolder follow the pattern {locale}.json where locase 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 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.

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 a various language editions of the Roman Missal in various regions within the same wider region, we opted to place this data not in the data/ folder but in a nations/ folder.

  • The liturgical data for each liturgical event for a wider region is defined in a resource file nations/{Wider_region}.json, where Wider_region is the English capitalized name of the wider region (i.e. Europe.json, Americas.json, 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 (i.e. {name of the feast}, 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. Even though this resource file also contains a name key with the display name of the liturgical event, this value will however be overriden by any translations present as indicated in the following paragraph.

  • The translatable data for the liturgical event can be found in a folder following the pattern nations/{WIDER_REGION}/ where WIDER_REGION has the exact same name as the aforementioned resource file for the wider region, but is in this case in uppercase rather than being capitalized. This is simply because this project was built piecemeal, one step at a time, without knowing at first how it would be built, so there were no pre-established conventions. Perhaps a better structure and better conventions can be defined in a future release of the API. There isn't really any specific source translation file in this case; simply at least one language resource must be initially defined and then others can be handled in the Weblate translation server. And in this case the translation files follow the pattern nations/{WIDER_REGION}/{locale}_{REGION}, 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...

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 data/propriumdesanctis_{REGION}_{YEAR}/ folder, where REGION is the region in which the language edition of the Roman Missal was published (i.e. ITALY or USA), and YEAR is the year in which the regional language edition of the Roman Missal was published. Preferring a reference to the REGION rather than to the language allows us to creating 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.

  • 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: data/propriumdesanctis_{REGION}_{YEAR}/propriumdesanctis_{REGION}_{YEAR}.json. This resource file defines the 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 nations/{REGION}/{REGION}.json, where REGION is the uppercase English name 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 data/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 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 data/propriumdesanctis_NETHERLANDS_{YEAR}/ folder, all the data is defined in the nations/NETHERLANDS/NETHERLANDS.json resource file.

Diocesan calendars

Resource files for diocesan calendars are to be found under the 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 data/ folder. The resource file for each diocese is found in nations/{REGION}/{Diocese}.json, where REGION is the uppercase English name of the region or country in which the language edition of the Roman Missal was published, and Diocese is the (generally) capitalized name of the Diocese (actual name of the diocese, not necessarily English). 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.

Clone this wiki locally