Calendar Governance Model - Liturgical-Calendar/LiturgicalCalendarAPI GitHub Wiki

The Liturgical Calendar API does not just model a hierarchy of calendar data — it models the Church's own governance of that data. This page explains the governance model from an ecclesial point of view, and how that model is encoded in the API's authorization system. For the technical implementation, see OpenFGA Fine-Grained Authorization.

The ecclesial entities

The Roman Catholic liturgical calendar is not maintained by a single central authority editing one dataset. Distinct ecclesial entities each hold real, proper authority over their own layer of the calendar:

The Holy See — through the Dicastery for Divine Worship and the Discipline of the Sacraments — promulgates the General Roman Calendar, the universal base calendar contained in the editiones typicae of the Roman Missal (1970, 2002, 2008), together with subsequent decrees that amend it (new memorials, changes of rank, doctors of the Church, etc.).
Conferences of Bishops establish national calendars (particular calendars) for their territories: proper celebrations of national patrons and locally venerated saints, and pastoral decisions such as whether Epiphany is kept on January 6th or transferred to a Sunday, and whether Ascension and Corpus Christi are celebrated on Thursday or on a Sunday.
Diocesan bishops establish diocesan calendars: the principal patron of the place, the anniversary of the dedication of the cathedral, and local memorials. A diocesan calendar builds on its national calendar, and — where the decision is left to the local level — may make a different pastoral choice than the nation regarding Thursday versus Sunday celebration of Ascension and Corpus Christi.
Vatican City participates in this system as a national calendar (VA), inherently in Latin. The General Roman Calendar is the universal calendar, not "the Vatican's calendar": even Vatican City has its own particular calendar, governed like that of any other nation.
Wider regions (Americas, Europe, Asia, ...) are not ecclesial juridical entities of their own. They are a shared data layer capturing celebrations common to the conferences of a geographical region — for example, Our Lady of Guadalupe as Patroness of the Americas. Because these shared celebrations affect every member nation, wider regions are governed jointly by their member nations rather than by a separate authority.

Hierarchical data, parallel governance

Calendar data inherits downward through a strict hierarchy:

General Roman Calendar     (universal: Roman Missal editions, temporale, decrees)
         ↓
    Wider Region           (celebrations shared across a region, e.g. Americas)
         ↓
 National Calendar         (Conference of Bishops; includes Vatican City as VA)
         ↓
 Diocesan Calendar         (diocesan bishop: local memorials, local overrides)

Governance, however, does not cascade down that same tree. It runs almost parallel at each level: each entity governs its own data and only its own data. Whoever administers the General Roman Calendar data has no authority over Italy's national calendar; the administrators of Italy's national calendar have no authority over the calendar of the Diocese of Rome. Granting someone edit access to one calendar says nothing about any calendar above or below it.

There are two deliberate exceptions where governance crosses layers:

Wider regions are governed by their member nations. An administrator of any member national calendar automatically holds administrative authority over the wider region. Since wider-region events apply to all member nations, their administrators jointly steward that shared layer.
The system administrator bootstraps governance. The first administrative grant on any resource is approved by a system administrator. From then on, that resource's administrator self-governs it — approving or revoking editor and viewer access for their own resource without further central involvement.

This reflects the principle of subsidiarity: decisions are taken at the level competent to take them, and each entity exercises proper authority over its own domain rather than receiving delegated authority from above.

Mapping to the authorization system

Each ecclesial layer corresponds to an object type in the API's fine-grained authorization model:

Ecclesial reality	Object type	Object IDs
Holy See / Dicastery for Divine Worship	`general_roman_calendar`	`temporale`, `EDITIO_TYPICA_1970`, `EDITIO_TYPICA_2002`, `EDITIO_TYPICA_2008`, `decrees`
Regional grouping of Conferences of Bishops	`wider_region`	Region names (e.g. `Americas`, `Europe`, `Asia`)
Conference of Bishops (incl. Vatican City)	`national_calendar`	ISO 3166-1 alpha-2 nation codes (e.g. `IT`, `US`, `NL`, `VA`)
Diocesan bishop	`diocesan_calendar`	Diocese identifiers (e.g. `romamo_it`, `rotter_nl`)

Every object type carries the same three relations, forming a strict superset chain (admin ⊇ editor ⊇ viewer):

Relation	Meaning	Authority granted
`admin`	Governance	Create (`PUT`) and delete (`DELETE`) the resource; everything below
`editor`	Data stewardship	Modify (`PATCH`) the resource's data; everything below
`viewer`	Read access	View restricted resource data

The distinction between governance and stewardship is enforced in the HTTP method mapping:

Creating or deleting a calendar is a governance act — it requires the admin relation.
Editing calendar data is a stewardship act — it requires only the editor relation.
Tests are the exception: creating a liturgical event test is itself an editorial act, so test creation requires only editor (deleting a test still requires admin).

Wider-region governance is derived rather than granted: the model records each nation's membership (wider_region:Americas has member_nation national_calendar:US, etc.), and anyone holding admin on a member national calendar inherits admin on the wider region through that membership. No separate wider-region grant exists or is needed.

Governance persists beyond data

When a calendar's data is deleted, the editor and viewer permissions on it are purged — but the admin permissions survive. The governing entity retains its authority over the resource even when the data is removed, so it can recreate the calendar later without re-requesting governance. Only when a user's underlying role is revoked entirely are all of their permissions, including admin, cascaded away.

The access workflow

Authorization operates in two layers (see Zitadel RBAC Overview for the first):

Role — the user obtains a Zitadel role (calendar_editor or test_editor) granting general access to the corresponding endpoints.
Resource permission — the user requests a relation (admin, editor, or viewer) on a specific resource via POST /auth/access-requests. A system administrator approves the first admin grant on a resource; that resource's administrators handle subsequent editor/viewer requests for it.

A request for admin on a national calendar may be prospective: the calendar need not exist yet. Approval grants governance over the nation's calendar, seeds its wider-region membership from the nation's metadata, and the new administrator can then create (PUT) the calendar definition.

For the step-by-step contributor workflow, see Editing calendars and tests. For the technical implementation of this model, see OpenFGA Fine-Grained Authorization.

Authentication & RBAC: ← [Zitadel RBAC Overview]] ](/Liturgical-Calendar/LiturgicalCalendarAPI/wiki/[[Home) | OpenFGA Fine-Grained Authorization →