Interoperable schemas for civic and public-interest information.
Note: This project is not affiliated with the Open Civic Data project started by the Sunlight Foundation (github.com/opencivicdata, documentation), which defines Open Civic Data Division Identifiers (OCD-IDs). Whether and how this project reuses OCD-IDs is an open decision tracked in #3.
Public-interest information such as the services a government offers, how it plans and spends its budget, and which bodies and office holders are responsible for what is usually published in formats that differ from one publisher to the next. Each reuser ends up writing a one-off parser, and comparing two cities or two agencies means reconciling their structures by hand.
Good standards already exist for parts of this problem: the Open Contracting Data Standard for procurement, Popolo for people, organizations and memberships, schema.org GovernmentService for describing services on the web, and the Frictionless Data Package and Table Schema specifications for tabular data. What is missing is a small, versioned, machine-checkable profile that ties them together for common civic datasets and comes with tooling that validates real files.
- A set of JSON Schema documents and Frictionless Data Package profiles for a few civic domains, starting with a public service catalog, budget and expenditure, and public bodies and mandates.
- A profile that references existing standards instead of duplicating them: where Popolo, OCDS or schema.org already defines a concept, the schema points to it and maps to it.
- A Python command-line tool,
ocd, intended to validate files against the schemas and convert CSV to JSON using Table Schema. - Documentation for each schema, with fictional example datasets clearly marked as examples.
- Not a replacement for OCDS, Popolo, schema.org or Frictionless Data. If a concept is covered there, this project defers to it.
- Not a data portal, a hosted API or a dataset collection. It defines formats and tools; publishers keep their own data.
- Not tied to a single country's legal or administrative model. Country-specific fields belong in extensions, not in the core schemas.
The v0.1.0 milestone is meant to deliver a first usable schema and the tooling around it:
- Repository scaffolding with uv, ruff, pytest and CI (#1).
- An ADR on schema versioning and governance (semantic versioning and a change process) (#2).
- An ADR on reusing OCD-IDs, Popolo and OCDS rather than reinventing identifiers and models (#3).
- A first "public service" schema aligned with schema.org GovernmentService (#4).
- The
ocd validatecommand (#5). - A CSV to JSON converter driven by Table Schema (#6).
- Fictional example datasets, labelled as examples (#7).
- Reference documentation for each schema (#8).
- Translated field labels in English, Brazilian Portuguese and Spanish (#9).
- Reuse before invention. A new field or identifier is added only after checking that OCDS, Popolo, schema.org, Frictionless Data or OCD-IDs do not already cover it, and the check is recorded in the pull request.
- Every schema is testable. Each schema ships with valid and invalid fixtures that run in CI.
- Versioned contracts. Schemas follow semantic versioning; a breaking change requires a major version and an ADR.
- Plain files first. Schemas, examples and documentation are plain JSON, CSV and Markdown that work without this project's tooling.
- Language-neutral data, translated labels. Field names are stable English identifiers; human-readable labels and descriptions are translated separately.
Look for issues labelled good first issue and read CONTRIBUTING.md before opening a pull request.