🗓️ Litcal Demo

Liturgical Calendar Resolver

Compare how this date is resolved across all available calendars

📐 Data Structure — What You Need to Configure

To create a custom liturgical celebration (diocese, religious order, etc.), you need to provide the following fields. These fields will be stored in JSON files and eventually in your database.

🎯 Celebration

Complete definition of a liturgical celebration

id string REQUIRED
Unique identifier in snake_case format (same as Romcal). You'll use this ID to fetch translated texts.
Example: "james_apostle", "our_lady_of_guadalupe"
rank Rank REQUIRED
Liturgical rank of the celebration. Determines its importance.
Values: "SOLEMNITY", "FEAST", "MEMORIAL", "OPTIONAL_MEMORIAL", "SUNDAY", "WEEKDAY"
precedence Precedence REQUIRED
Liturgical precedence according to UNLY §59. Defines which celebration "wins" when there's a conflict.
Values: "GENERAL_SOLEMNITY_3", "GENERAL_FEAST_7", "PROPER_FEAST_PRINCIPAL_PATRON_OF_DIOCESE_8A", "GENERAL_MEMORIAL_10", etc.
See full precedence list →
colors Color[] REQUIRED
Array of liturgical colors for this celebration (can have multiple).
Values: ["RED"], ["WHITE"], ["GREEN"], ["PURPLE"], ["ROSE"], ["BLACK"], ["GOLD"]
Multiple example: ["WHITE", "GOLD"]
isHolyDayOfObligation boolean REQUIRED
Is it a holy day of obligation? (required Mass attendance)
Values: true | false
isOptional boolean REQUIRED
Is it optional to celebrate? (e.g., optional memorials)
Values: true | false
metadata object OPTIONAL
Additional custom data. You can store whatever you need here.
Example: { "romcalName": "Saint James", "periods": ["CHRISTMAS"] }

🏆 Precedence Values

Liturgical precedence order (from highest to lowest priority)

TRIDUUM_1 — Paschal Triduum
PROPER_OF_TIME_SOLEMNITY_2 — Solemnities of the Proper of Time
PRIVILEGED_SUNDAY_2 — Privileged Sundays
ASH_WEDNESDAY_2 — Ash Wednesday
WEEKDAY_OF_HOLY_WEEK_2 — Weekdays of Holy Week
WEEKDAY_OF_EASTER_OCTAVE_2 — Days of the Easter Octave
GENERAL_SOLEMNITY_3 — Solemnities of the General Calendar
PROPER_SOLEMNITY_PRINCIPAL_PATRON_4A — Solemnity of the Principal Patron
PROPER_SOLEMNITY_DEDICATION_OF_THE_OWN_CHURCH_4B — Dedication of the Cathedral/Own Church
GENERAL_LORD_FEAST_5 — Feasts of the Lord in the General Calendar
UNPRIVILEGED_SUNDAY_6 — Sundays of Ordinary Time
GENERAL_FEAST_7 — Feasts of the General Calendar
PROPER_FEAST_PRINCIPAL_PATRON_OF_DIOCESE_8A — Feast of the Principal Patron of the Diocese
PROPER_FEAST_DEDICATION_OF_CATHEDRAL_8B — Dedication of the Cathedral
PROPER_FEAST_PRINCIPAL_PATRON_OF_REGION_8C — Principal Patron of the Region
GENERAL_MEMORIAL_10 — Memorials of the General Calendar
PROPER_MEMORIAL_11B — Proper Memorials
OPTIONAL_MEMORIAL_12 — Optional Memorials
WEEKDAY_13 — Weekdays of Ordinary Time

📋 CalendarRule

Defines how to add/modify/suppress a celebration in the calendar

id string REQUIRED
Unique rule ID
calendarId string REQUIRED
Which calendar this belongs to
Example: "spain", "diocese-madrid", "order-dominicans"
action RuleAction REQUIRED
What to do with the celebration
Values: "ADD" (add new), "REPLACE" (elevate rank/modify), "SUPPRESS" (remove), "TRANSFER" (move to another date)
celebration Partial<Celebration> REQUIRED
The celebration data (see structure above). For REPLACE actions, only include fields to modify.
dateRule DateRule REQUIRED
Rule that defines when the celebration occurs
{ "type": "fixed", "month": 7, "day": 25 } — Fixed date (July 25)
{ "type": "easter-relative", "addDays": 39 } — Relative to Easter (Ascension)

✅ Complete JSON Example

{
  "id": "spain-santiago-apostle-solemnity",
  "calendarId": "spain",
  "action": "REPLACE",
  "targetCelebrationId": "james_apostle",
  "celebration": {
    "id": "james_apostle",
    "rank": "SOLEMNITY",
    "precedence": "PROPER_SOLEMNITY_PRINCIPAL_PATRON_4A",
    "colors": ["RED"],
    "isHolyDayOfObligation": true,
    "isOptional": false,
    "metadata": {
      "romcalName": "Saint James, Apostle"
    }
  },
  "dateRule": {
    "type": "fixed",
    "month": 7,
    "day": 25
  }
}