ADR 035: Interface Standards throughout Platform
Date: 2026-03-10
Status: Reviewed
Decision Makers: CIVITAS/CORE Architecture Board
Context
CIVITAS/CORE integrates multiple platform components, external systems, and public interfaces. These interfaces must be understandable, reusable, and stable across different teams, cities, and integration scenarios.
If each component defines its own formats and protocol conventions without shared standards, the result is higher integration effort, more custom transformation logic, and weaker interoperability. This is especially problematic for public interfaces and for interfaces that cross component boundaries.
Several standards are already relevant in the platform context, for example:
- JSON and JSON Schema for structured payloads and schema definitions
- REST and, where appropriate, OData for service APIs
- CloudEvents for event envelopes on the message bus
- DCAT-AP.DE for metadata and catalog interoperability
- XML, XMI, or UML-based exchange formats where specific modeling tools or established external standards require them
The platform therefore needs a clear standard-first rule for interface design.
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
- [full] Self-contained deployment
- [full] Technological consistency to ensure maintainability
- [partial] Multi-tenancy
- [partial] Security by design
Comments on partial ratings:
- Multi-tenancy: Standards improve interoperability, but tenant isolation and tenant-specific access rules still have to be implemented at the application and deployment layers.
- Security by design: Standards help define and review interfaces consistently, but secure authentication, authorization, and data protection still need explicit implementation.
Decision
All CIVITAS/CORE interfaces must follow a standard-first approach.
This means:
- Open and established standards are used wherever they reasonably fit the use case.
- Public and cross-component interfaces must be explicitly specified and versioned.
- JSON is the default data format for API payloads unless another standard is required.
- JSON Schema is the preferred machine-readable schema format for JSON payloads.
- REST is the default API style; OData may be used where it provides concrete benefits for queryable business data.
- CloudEvents is used for event envelopes on the message bus in line with ADR 013.
- Domain-specific standards such as DCAT-AP.DE are used where interoperability with external ecosystems depends on them.
- Proprietary or ad hoc formats are only acceptable with explicit justification.
Consequences
- Interface definitions become easier to document, review, and govern across the platform.
- External integrations benefit from better interoperability and lower onboarding effort.
- Component teams must justify deviations from standards instead of inventing local conventions by default.
- Some use cases may require adapters or transformation layers where an external system cannot consume the platform's preferred standards directly.
- Architecture reviews should treat interface design as a first-class concern, especially for public APIs and inter-component contracts.
Alternatives
- Custom formats per component: Rejected because this increases integration cost and weakens interoperability.
- Protocol freedom without governance: Rejected because it leads to inconsistent interfaces and unnecessary long-term maintenance burden.
- Single standard for every interface type: Rejected because different interface categories have different needs; the decision is to prefer standards, not to force one protocol onto every problem.