Editing calendars and tests - Liturgical-Calendar/LiturgicalCalendarAPI GitHub Wiki

The Liturgical Calendar project allows qualified liturgists to contribute by editing national and diocesan calendar definitions, or by creating and maintaining liturgical event correctness tests. Both workflows require registering on the Liturgical Calendar website and requesting the appropriate role.

Becoming a calendar editor

Calendar editors can modify national and diocesan calendar definitions through the API's /data endpoint. This includes adding, updating, or removing liturgical events specific to a national or diocesan calendar.

Step 1: Register and verify your email

Create an account on the Liturgical Calendar website using the Zitadel login flow. Verify your email address to activate your account.

Step 2: Request the calendar editor role

From the Request Access page, select the calendar_editor role. You can provide a justification explaining your qualifications (e.g., diocesan liturgy commission member, seminary professor). An administrator will review your request.

Step 3: Request permission for specific calendars

Once your role is approved, you need to request edit access for the specific calendars you intend to work on. From the Permission Requests page, submit a request with:

  • Object type — national_calendar or diocesan_calendar
  • Object ID — the calendar identifier (e.g., IT for Italy, US for the United States, or a diocesan key like rotter_nl for the Diocese of Rotterdam)
  • Relation — editor
  • Justification — why you need access to this specific calendar
  • Credentials — any supporting references (e.g., appointment letter, institutional affiliation)

An administrator will review the request and, if approved, grant you edit access to that specific calendar.

Step 4: Edit calendar data

With the calendar_editor role and editor permission for a specific calendar, you can edit calendar definitions through the administration area of the Liturgical Calendar website. The website provides a form-based interface for managing national and diocesan calendar data, accessible from the Extending the calendar page once you are logged in with the appropriate permissions.

For technical reference, the underlying API endpoints are:

  • PUT /data/nation/{calendar_id} — update a national calendar definition
  • PATCH /data/nation/{calendar_id} — partially update a national calendar definition
  • PUT /data/diocese/{calendar_id} — update a diocesan calendar definition
  • PATCH /data/diocese/{calendar_id} — partially update a diocesan calendar definition

Becoming a test editor

Test editors can create and maintain liturgical event tests — JSON-based definitions that verify the liturgical correctness of the calendar output across years. These tests ensure that events fall on the right dates, respect precedence rules, and appear only in the years they should.

Step 1: Register and verify your email

Same as for calendar editors — create an account and verify your email.

Step 2: Request the test editor role

From the Request Access page, select the test_editor role with a justification explaining your liturgical knowledge. An administrator will review your request.

Step 3: Request permission for a test scope

Test permissions are granted per calendar scope, not per individual test: editor permission for a scope lets you create and edit any test that applies to that calendar. Once your role is approved, submit a request with:

  • Object type — national_calendar_test, diocesan_calendar_test, or general_roman_calendar_test
  • Object ID — the nation code (e.g., NL) or diocese ID (e.g., rotter_nl); for General Roman Calendar tests the scope is simply general_roman_calendar
  • Relation — editor

Step 4: Create or edit tests

With the test_editor role and editor permission, you can create and manage test definitions through the Unit Test interface, which provides a user-friendly interface for defining assertions about liturgical events. See Unit Test server and interface for details on the test frontend.

Test definitions are JSON files that specify assertions about liturgical events across calendar years. See Liturgical event tests for the full JSON structure, test types, and assertion format.

For technical reference, the underlying API endpoints are:

  • POST /tests — create a new test definition
  • PUT /tests/{test_name} — update an existing test definition
  • DELETE /tests/{test_name} — remove a test definition

How permissions work

The permission system has two layers:

  1. Role-based — the calendar_editor or test_editor role grants general access to the corresponding API endpoints
  2. Resource-specific — fine-grained permissions (managed via OpenFGA) control which specific calendars or test definitions you can edit

This means having the calendar_editor role alone is not sufficient — you must also have editor permission for the specific calendar you want to modify. This ensures that each calendar is maintained only by authorized individuals with the relevant liturgical expertise.

The permission structure mirrors the Church's own governance of the liturgical calendar: the Holy See, Conferences of Bishops, and diocesan bishops each govern their own layer of calendar data. See Calendar Governance Model for the full picture, and OpenFGA Fine-Grained Authorization for the technical details.

For Liturgists | Home