# Contributing through the Admin Panel

The Admin Panel lets third parties such as parliamentary services, researchers or civil
society organisations contribute their expertise directly to OpenParlData.ch. They work
within defined boundaries: the official data published by the parliaments stays untouched,
and every change is attributable and reversible. This page describes how this works, using
the harmonisation of affair types as the example.

## Controlled Contributions

OpenParlData.ch already operates the technical mechanism for a formalised contribution
process: the **Admin Panel** (<https://admin.openparldata.ch>). It corresponds to option
(ii) in the typology of external community governance[^dpg] — external contributors can
change data, but only within defined boundaries, and every change remains attributable
and reversible.

The Admin Panel is the editorial back office of the platform. It provides the configuration needed to control the mapping and ETL processes, such as defining how affair types and status designations correspond across parliaments, and how each body and its data delivery are described.

Much of this configuration is publicly accessible, making these settings transparent. To contribute, users sign in with an existing GitHub, GitLab, or Google account and can request an Editor or Admin role.

Three properties make these contributions controlled rather than merely open:

Role-based access
: Permissions can be assigned to different contributors at a granular level, with different rights for different parts of the OpenParlData configuration. For example, one contributor may be allowed to edit the mapping of affair types, while another can manage ETL settings.

Bounded scope
: Contributors do not edit the source records harvested from the parliaments. The
  official data as published by each body stays untouched; contributions are made in a
  separate harmonisation layer on top of it. This keeps the provenance of official data
  intact and makes the contributed interpretation distinguishable from the source.

Traceability
: Every change is written to an audit trail with user, timestamp and the affected records.

:::{figure} ../img/admin_permission_matrix.png
:alt: Admin Panel, Permission Matrix: table of permissions against the roles Public, User, Editor, Admin and Owner
:width: 100%

Admin Panel, *Permission Matrix*: every permission the panel knows, listed against the
roles. The Public column shows what is visible without an account at all. The rows make
the separation of viewing, configuring and updating visible for each data domain.
:::

## Example: Harmonised Affair Types and Their Mapping

The harmonisation of affair types is the first data domain opened up in this way, and it illustrates why external expertise is needed. Swiss parliaments use different names for comparable parliamentary procedures, while the same name can have different legal meanings. For example, Basel-Stadt uses the term Anzug for a procedure that corresponds to the Postulat at federal level and in most cantons. Deciding which such procedures should be mapped to the same affair type is a question of parliamentary law, not one the ETL pipeline can answer.
The Admin Panel therefore splits the task into two views:

**Types** ([admin.openparldata.ch/#/affair_types_harmonized?tab=types](https://admin.openparldata.ch/#/affair_types_harmonized?tab=types))
holds the controlled vocabulary of harmonised affair types, each with names in German,
French, Italian, Romansh and English, a defined display order, and, where one exists, a
Wikidata identifier. This catalogue is what makes affairs comparable across bodies. It is
deliberately small and curated, and the Wikidata reference anchors each category in an
identifier outside our own infrastructure, so that third parties can align their
vocabularies with ours without having to adopt our keys. The catalogue is a practical
proposal rather than a final classification: it is being aligned with other stakeholders
and reviewed as part of the proposed eCH standard for parliamentary affairs,
[eCH-0295](https://github.com/swiss/political-affairs-ech-group/tree/main/ech-0295_affairs),
whose draft schema defines its own list of affair types, such as motion, postulate,
interpellation and parliamentary initiative.

**Mapping** ([admin.openparldata.ch/#/affair_types_harmonized?tab=mapping](https://admin.openparldata.ch/#/affair_types_harmonized?tab=mapping))
assigns every original affair type, as delivered by a body in its own language, to exactly
one harmonised type. Each assignment can carry a comment and typed evidence links, either
to the legal basis (`legal_basis`) or to an explanatory source (`description`), with the
language and an optional reference number; changes to these sources are kept in a per-entry
history. The list can be filtered by body, language, harmonised type and status, so
entries that are still unmapped or that lack a comment or a source can be listed directly.
This turns the open harmonisation work into a reviewable backlog rather than an opaque
decision inside the pipeline.

:::{figure} ../img/admin_affair_types.png
:alt: Admin Panel, Types tab: catalogue of harmonised affair types with multilingual names
:width: 100%

Admin Panel, *Types*: the curated catalogue of harmonised affair types, with names in five
languages, the number of affairs currently assigned to each type, and the corresponding
Wikidata identifier.
:::

:::{figure} ../img/admin_affair_types_mapping.png
:alt: Admin Panel, Mapping tab: original affair types per body assigned to harmonised types
:width: 100%

Admin Panel, *Mapping*: each original affair type as delivered by a body, with its
language, the number of affairs affected and the harmonised type it is assigned to.
Entries still awaiting a decision are marked as not assigned. The icons next to each
assignment hold its sources and comments, and the last column records who last changed it
and when.
:::

What this arrangement already provides is authorisation, attribution and reversibility.
What it does not yet define is the editorial process around it: who reviews a contributed
mapping before it is published, how contributors are notified of decisions, and how
conflicting interpretations between bodies are resolved.

[^dpg]: <https://ash.harvard.edu/wp-content/uploads/2024/02/best_practices_for_the_governance_of_digital_public_goods.pdf>
