Commons Database
Data Model Foundation
The Commons Database data model will be inspired by, and structurally based on, the Open Fibre Data Standard (OFDS). OFDS is a common data standard jointly developed by the World Bank, the International Telecommunications Union (ITU), Mozilla Corporation, and other partners for describing terrestrial fibre optic infrastructure. It provides a structured logical data model (entities, relationships, attributes, and codelists) covering the location, technical characteristics, and administrative ownership of fibre infrastructure, along with publication formats in JSON, GeoJSON, and CSV. [open-fibre-data-standard.readthedocs]
Adopting OFDS as the baseline gives the project a globally recognized, interoperable schema for core network topology — nodes, spans, and physical/technical attributes — rather than inventing a proprietary structure from scratch.
Extending Beyond OFDS: Last-Mile and Community Network Functionality
OFDS was designed primarily around backbone and middle-mile fibre infrastructure (PoPs, transmission spans, IXPs) and does not natively model last-mile access networks or several operational concepts that community networks require, such as detailed device/interface inventories, wireless links, service subscriptions, or granular participant roles.
To cover this gap, the schema will be extended by drawing on the data models used by earlier community-network platforms, most notably guifi.net, whose network description has historically been expressed through the Community Networks Markup Language (CNML) — an XML-based schema describing registered nodes, links, devices, and their configurations, updated on a recurring snapshot basis. Other comparable community-network data models will also be reviewed for reusable patterns (e.g., device/interface granularity, zone hierarchies, and link/topology attributes). [A Technological overview of the guifi.net community network]
In practice, this means:
- OFDS entities (nodes, spans, contracts, organizations) form the backbone/middle-mile core of the schema.
- CNML-derived concepts (zones, devices, interfaces, wireless/last-mile links, node status lifecycle) extend the model to cover access-layer and community-governance needs not addressed by OFDS, so extending it.
- The combined schema is designed to remain a superset that can be exported (for example, with drupal Views data export) generating a valid OFDS-compliant subset for interoperability with external fibre-mapping tools such as OFDS CoVE.
Base Implementation: Headless Drupal
The first implementation of this extended schema will be built on a headless Drupal instance [2]. Drupal was chosen because its module ecosystem substantially accelerates delivery of the surrounding platform features without custom development:
- Mapping — geospatial/GIS modules for rendering nodes, links, and coverage areas.
- Access control & granularity — Drupal's entity/field-level permissions and role system allow fine-grained control over who can view or edit specific node, device, or organizational data.
- Integrations — Drupal's contributed-module ecosystem (migration, webhooks, third-party connectors) simplifies linking the database to monitoring, ticketing, or provisioning systems.
Using Drupal also facilitates migration and synchronization with legacy instances running earlier guifi.net-style schemas [1], [2, thus accelerating the development,
API Exposure: REST, JSON:API, and OpenAPI Documentation
All data will be exposed to any development framework through Drupal's built-in REST and JSON:API modules, so external applications, dashboards, or scripts can consume and extend Commons Database functionality independently of the Drupal backend.
Both APIs will be self-documented via Drupal's OpenAPI UI module, which generates and displays interactive Swagger UI documentation directly from the enabled REST and JSON:API resources. [codeenigma]
- Swagger UI explorer (browsable, for both REST and JSON:API resources): `/admin/config/services/openapi`
- Raw OpenAPI specification for JSON:API: `/openapi/jsonapi?_format=json`
- Raw OpenAPI specification for core REST resources: `/openapi/rest?_format=json`
These OpenAPI documents let any development environment — regardless of programming language or framework — auto-generate client bindings, validate payloads, and discover available endpoints without needing to inspect Drupal internals directly. This is intended to lower the barrier for third parties to build extensions, dashboards, or integrations on top of the Commons Database without depending on the core Drupal codebase. [codeenigma]