filter parameter for limited sets of calendar events

[jfacemyer]

I looked around a bit, but didn't see an option for changing output content, not giving the vigil information on Saturdays, or preferring a Saint's proper memorial over an optional BVM on Saturdays, and only give the BVM if there's nothing else? (e.g. output the highest ranking or a preferred type each day?)

I was thinking about digging in and looking at implementing this, possibly, but wanted to know if this exists or was desired or was in the works already.

[JohnRDOrazio]

Hi @jfacemyer , the main purpose of this API is to output the correct liturgical celebrations for each day in a given calendar year, either in the universal roman calendar or for a specific nation or even a specific diocese.
If there is an optional memorial on any given day, it will be output alongside the weekday, because it's optional. So if for example a Mass app were to use this calendar, there would be a choice of using the liturgical texts for the optional memorial or for the weekday. So in cases like that, no there is no option to output only one result, because how would choose which result to output? They're both equally important.
I decided to incorporate Vigils into the calendar because that is also an important liturgical calculation: when there are two solemnities next to each other, which one has precedence when it comes to vigil masses / first vespers / second vespers? This is again important for any Mass app or breviary app or diocesan liturgical calendar, because it will determine which liturgical texts should be used for first vespers / second vespers or which Mass should be celebrated.
The Saturday memorial of the Blessed Virgin Mary should only appear where it is permitted. If you see it appearing where it is not permitted please let me know.

[jfacemyer]

Ok, I get that.

Does it mean you would not be interested in a parameter to filter output like this, if I wanted to work on that?

[JohnRDOrazio]

I believe that if anything this could be done in a client implementation. Changing it on the server output would in my opinion be confusing and would require creation of more parameters which would make the endpoint even more confusing.
However it is not difficult to create filters in a client implementation. For example, to remove vigil masses, you can delete any items in the JSON object that contain the word "vigil" in the name of the celebration (if your client is using English).
I suppose to make it even easier to do for any language, I could create a new property "isVigilMass" in the resulting JSON object to clearly identify Vigil Masses, so as to be able to target them and filter them out. In fact, celebrations that have Vigil Masses already have a property "hasVigilMass" set to true, for example:

"MotherGod":{"name":"Maria Ss.ma Madre di Dio","color":"white","type":"fixed","grade":6,"common":"","date":"1609459200","displaygrade":"","eventidx":44,"liturgicalyear":"ANNO B","hasVigilMass":true,"hasVesperI":true,"hasVesperII":true}

But being able to target the actual Vigil Mass event isn't quite so straightforward, without searching for the term "vigil" in the name of the celebration. That I can do.

[JohnRDOrazio]

I have added the isVigilMass property to better identify Vigil Masses:

• 9cd59f1
• 644ca56
  It is now available for usage on the staging API endpoint, for example:
  https://johnromanodorazio.com/LiturgicalCalendar-staging/LitCalEngine.php?returntype=JSON

Now it is very easy to target Vigil Mass events and filter them out from the results. I hope this fixes for you.

[jfacemyer]

Ok, thanks - I'll look at a client implementation!

[HPaulson]

@JohnRDOrazio I was going to make a similar suggestion/offer to implement filters and found this old issue.

It makes sense for a mass readings or breviary app that filtering should be done client-side, but I'm wondering about the iCal use-case. For people who use the API to subscribe to events inside their calendar app, it might be useful to have an option to filter by type of feast or other filters. One might only want to subscribe for solemnities, for example. This makes a ton of sense because the weekdays, optional memorials, etc can be very bloating to a calendar already filled with work and personal events. So a user might still want to see what the non-feria days on the calendar are, but not the rest. This is my reason for desiring such a filter feature, at least. I wonder your thoughts on this.

[JohnRDOrazio]

My thoughts are, I can see what you're trying to get at, but I still think it would be simpler to adopt in a client application because there are so many different ways a filter could be applied, how could the API have a filter that would make everyone happy?
What if one person would like to see all Feasts and Solemnities, another would like to see Feasts of the Lord and Solemnities, another would like to see only Holy Days of Obligation... Among the Feasts of the Lord, Sundays are also counted: what if someone wanted to see Feasts of the Lord but not Sundays of Ordinary Time?
I can see your point, but I can also see how arbitrary the filters could be. So I can't possibly see how to apply a filter reliably in the API. If you have any suggestions on how to go about doing this in a way that everyone would be happy, I might consider it. But there needs to be some objective criteria to the filter, and not just an arbitrary "I'm seeing too many entries in my calendar for my liking".

[HPaulson]

You're right - there's a LOT of filter options that could be useful. For this reason, I think it makes sense for filtering like this to be very arbitrary. I made a demo in deno/typescript with the type of system I think would be best here. It is modeled off a similar system in Directus. I ended up making it fairly complete, so my use case is satisfied, and I'm happy to close this if you don't think it's worth implementing in the actual api.

The only example we mentioned above that I could not implement using the generic filter options is only including Holy Days of Obligation. This is because I couldn't find any data field that relates to this, which makes sense because it'll be different in each diocese. Perhaps this could be added, similar to is_vigil_mass, on the diocese calendars that do exist?

. . .

I realize this system makes filtering fairly technical, because it requires an understanding of the json data and each type. Perhaps in the examples above there are even some mistakes. This would make it hard to add "human readable" names to these filters, but at least it gives a developer the chance to filter for their needs (and attempt the human readable if desired).

[JohnRDOrazio]

Great work! I haven't in fact implemented a Holy Day of Obligation property yet, I'll try to fix that. How could we name such a property? In Latin it's "dies festus de praecepto", in Italian it's "festa di precetto", in English it's "Holy Day of Obligation", as stated in the Code of Canon Law in canon 1246:

• Latin https://www.vatican.va/archive/cod-iuris-canonici/latin/documents/cic_liberIV_la.html#:~:text=Can.%201246%20%E2%80%94%20%C2%A7%201,omnium%20denique%20Sanctorum.
• Italian https://www.vatican.va/archive/cod-iuris-canonici/ita/documents/cic_libroIV_1246-1248_it.html#%C2%A72:~:text=Can.%201246%20%2D%20%C2%A71,tutti%20i%20Santi.
• English https://www.vatican.va/archive/cod-iuris-canonici/eng/documents/cic_lib4-cann1244-1253_en.html#TITLE_II.:~:text=Can.%C2%A01246%20%C2%A71,and%20All%20Saints.

Seeing the other properties are defined in English, perhaps for consistency we should stick to English and name it: is_holy_day_of_obligation with a boolean value of true or false. And rather than attach the property to every single event, perhaps it should only be attached to events that have a rank of "Feast" and up. "Feast of the Lord" (one rank higher than "Feast") would almost be enough, except that I'm seeing on https://en.wikipedia.org/wiki/Holy_day_of_obligation that in the Dominican Republic, the Feast of Our Lady of Altagracia and the Feast of Our Lady of Mercy are also considered Holy Days of Obligation (though they're probably Solemnities anyways?) and in Germany Saint Stephen's Day is also considered a Holy Day of Obligation (not sure if it's also considered a Solemnity in Germany?). Just to be on the safe side, I'll attach the property to events ranking Feast and up.

I suppose it could be useful to be able to add "middleware" to the API, that would allow to add extra functionality such as the filter you have implemented. But I could probably use some help in working out a good architecture for allowing different kinds of middleware to be implemented... I suppose there could be a middleware folder, where any scripts found in the folder would be run automatically by the API. But then we would have to have an understanding of what kinds of middleware scripts would be placed there, and how and when they should be run...

[JohnRDOrazio]

Or perhaps any middleware would be implemented in client libraries for the API, rather than in the API itself...

[HPaulson]

This seems reasonable. Perhaps middleware/extentions could be supported in a way that is agnostic to language. Here's one idea, taking some inspiration from package.json scripts:

• Have an extensions folder, which has a sub-folder for each middleware/extention.
• Each subfolder must have a extension.json top-level file. This file will describe the behavior of the extention. Example:

{
"name": "MyExtention1",
"version": "0.0.1",
"LitCalVersion": "^4.3",
"author": "MyName",
"github": "https://github.com/project/name",
. . .
"build": "deno task build",
"start": "deno run main.ts"
}

Using a setup like this one, the build command would be run on API-start. On each api request, a temp file would be created after the api generates the relevant response for that request, so that each extention can successively take in and modify the file's data. Order would be determined by some config file perhaps, or alphabetically? This file could contain the original args sent to the api, and the current json/ical/xml... data being processed (See example below). On each request, after this file is created, the start command of each middleware is called, with a flag designating the filepath of the temp file. After the api runs each middleware start command, it sends the new data in the file as the response. Each middleware, therefore, is responsible for taking in the correct file from the command argument, editing as necesary, and exiting the process when finished.

The temp file could also be a json file, somehting like this (but with all data available):

{
"queryParams": "?locale=en_us&year=2024...",
"endpoint": "/calendar/nation/US",
. . .
"type": "<json | yml | xml | ics>",
"data": "<json,yml,xml,ics data string>"
}

This setup would make it so self-hosted instances of the API can add n number of extentions they see fit, and it is very customizable. An extention can ignore requests based on the data in the file, can be built in any language, and can do pretty much anything it wants with the data. Of course these extentions would not be supported by the main insance of the api (for security reasons, and because not everyone would want to use them), but that's entiely ok I think.

Note that the self hosted instance would need to self-install any required software beforehand, like deno in the above example. Perhaps this could be standardized further by using make files that are called.

Unsure if this is the best solution for extentions, but the first one that came to mind. Curious your thoughts.

--

Regarding holy day of obligation, your idea LGTM. That should probaly become a seperate issue, though.

[JohnRDOrazio]

Holy Days of Obligation are now available in v5.2 (currently reachable at https://litcal.johnromanodorazio.com/api/v5/ !