ADR 041: Revised Topic Naming Convention for Configuration Events

Date: 2026-03-26

Status: Accepted

Decision Makers: Architecture Board

Context

ADR 021 established the initial topic naming convention for configuration events on the KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. message bus. The original convention used the prefix ccc (CIVITAS Core Configuration) followed by a tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. identifier, domain, entity, and operation/event:

ccc.<tenant>.<domain>.<entity>.<operation|event>

During implementation, the naming convention evolved to better align with established conventions in the Java/KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. ecosystem and to reduce unnecessary complexity. The changes were driven by the following observations:

1. Reverse domain name convention: The Java ecosystem and CloudEvents specification use reverse domain names as identifiers. Using de.civitascore as a prefix aligns the topic namespace with the CloudEvents type attribute convention and makes the origin of events unambiguous across systems.

2. TenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. segment removed: The original convention included a tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. segment in the topic name. In practice, tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. isolation is handled at the KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. cluster or ACL level, not by encoding the tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. into every topic name. Removing the tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. segment simplifies topic names and avoids an unnecessarily deep hierarchy.

3. Confirmation events only: The implemented convention uses exclusively past-tense event names (e.g., user.created, route.deleted). Command topics (imperative form) are not part of the configuration event namespace. This reflects the actual event-driven architecture where configuration events represent state changes that have already occurred.

4. Composite event types: Some events require multi-part event names (e.g., password.changed, password.reset). The convention supports dot-separated sub-segments for the event type, which was not explicitly defined in ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 021.

The revised convention is already in use across all implemented configuration adapters and the Portal Backend.

Checked Architecture Principles

• [full] Model-centric data flow
• [full] Distributed architecture with unified user experience
• [full] Modular design
• [full] Integration capability through defined interfaces
• [full] Open source as the default
• [full] Cloud-native architecture
• [full] Prefer standard solutions over custom development -- reverse domain naming is a widely adopted convention
• [full] Self-contained deployment
• [full] Technological consistency to ensure maintainability -- consistent with CloudEvents and Java conventions
• [full] Multi-tenancy -- tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. isolation via cluster/ACL level, not topic naming
• [full] Security by design

Decision

The topic naming convention for configuration events defined in ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 021 is revised as follows.

Revised Convention

Configuration event topics use the reverse domain prefix de.civitascore, followed by the platform domain, entity, and event type:

de.civitascore.<domain>.<entity>.<event>

Segment	Description	Examples
de.civitascore	Fixed platform prefix (reverse domain)	--
<domain>	Platform domain (lowercase abbreviation)	idm, api, data
<entity>	Platform entity (lowercase, no separators)	user, realm, backend, route, project
<event>	Event type (past tense, dot-separated for composites)	created, updated, deleted, password.changed

Changes Compared to ADR 021

Aspect	ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 021	This ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded.
Prefix	ccc	de.civitascore
TenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. segment	Included (<tenant>)	Removed -- tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. isolation via cluster/ACL
Topic types	Operations (imperative) and confirmations (past tense)	Confirmation events only (past tense)
Composite events	Not defined	Supported via dot-separated sub-segments (e.g., password.changed)
Domain naming	idm, apim, geodata	idm, api, data (shortened where applicable)

Configuration Event Domains

Domain	Abbreviation	Entities
Identity Management	idm	user, realm, client, group, role
API Management	api	backend, route
Data Management	data	thing, location, sensor, observedproperty, datastream, project, pipeline

Examples

de.civitascore.idm.user.created
de.civitascore.idm.user.deleted
de.civitascore.idm.user.password.changed
de.civitascore.idm.user.password.reset
de.civitascore.idm.realm.created
de.civitascore.idm.client.updated
de.civitascore.idm.group.deleted
de.civitascore.idm.role.created
de.civitascore.api.backend.created
de.civitascore.api.route.deleted
de.civitascore.data.project.created
de.civitascore.data.pipeline.deleted
de.civitascore.data.sensor.updated

Extending the Event Catalog

New configuration events follow the same convention:

1. Identify or define the domain abbreviation
2. Define the entity name (lowercase, no separators)
3. Use past tense for the event type
4. Use dot-separated segments for composite event types

Unchanged from ADR 021

The following aspects of ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 021 remain in effect and are not modified by this ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded.:

• CloudEvents envelope: Configuration events continue to use the CloudEvents standard as the message envelope (ADR 013)
• JSON payloads: Event payloads are JSON structures containing only the data required for the event
• SDK requirement: All producers and consumers must use the official CloudEvents SDKs

Consequences

• All existing configuration event topics already follow the revised convention. No migration is required.
• New configuration events must use the de.civitascore.<domain>.<entity>.<event> format.
• The ccc.* prefix from ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 021 is deprecated and must not be used for new topics.
• Topic-level ACL rules can use de.civitascore.* as a wildcard base for all configuration events, and de.civitascore.<domain>.* for domain-scoped access.
• The removal of the tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. segment from topic names requires that tenantTenantAn isolated organizational partition that owns Data pools, Datasets, Users, Groups, and Roles. All access rules exist within their Tenant, and the Tenant is the widest Scope of a Role. Currently, one Tenant corresponds to the Platform. isolation is enforced at the KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. cluster or ACL level.

Alternatives

• Keep ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 021 convention unchanged: Rejected because the implementation has already diverged, and the revised convention offers concrete advantages (ecosystem alignment, simpler names, clearer scoping).
• Introduce a new prefix while keeping ccc.*: Rejected to avoid maintaining two parallel naming conventions.

See also

• ADR 021: Definition of Configuration Events (superseded in part by this ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded.)
• ADR 013: Use CloudEvents Standard for Bus-based Configuration Communication
• ADR 026: Select Message Bus
• Topic Configuration: Full event catalog and topic reference