feat(specifications): add unlisted specification registry built from data files

.claude/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "mkdocs-en",
+      "runtimeExecutable": "mkdocs",
+      "runtimeArgs": ["serve", "-f", "config/en/mkdocs.yml", "--dev-addr", "127.0.0.1:8000", "--watch", "overrides", "--watch", "hooks", "--watch", "data", "--watch", "scripts"],
+      "port": 8000
+    },
+    {
+      "name": "mkdocs-en-alt",
+      "runtimeExecutable": "mkdocs",
+      "runtimeArgs": ["serve", "-f", "config/en/mkdocs.yml", "--dev-addr", "127.0.0.1:8001"],
+      "port": 8001
+    }
+  ]
+}

.github/ISSUE_TEMPLATE/specification-change.yml

@@ -0,0 +1,57 @@
+name: Specification registry change request
+description: Correct or add an entry in the MDIP specification registry (/specifications).
+title: "Change request: "
+labels: ["specification-registry"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Each specification and organization in the registry is one file in
+        [`data/`](https://github.com/MobilityData/Mobility-Data-Interoperability-Principles/tree/main/data), described in
+        [`data/README.md`](https://github.com/MobilityData/Mobility-Data-Interoperability-Principles/blob/main/data/README.md).
+        The quickest way to change an entry is "Suggest a change" on its page, which opens
+        its file for editing. Use this form to report a problem or ask a question instead.
+
+        Every change is discussed here in public before it is merged.
+  - type: input
+    id: spec_id
+    attributes:
+      label: Specification id
+      description: The file name in `data/specifications/`, without `.md`, for example `gtfs-schedule`. Leave empty to propose a new specification.
+    validations:
+      required: false
+  - type: dropdown
+    id: change_type
+    attributes:
+      label: Type of change
+      options:
+        - Correct an existing entry
+        - Add a new specification
+        - Add or correct an organization
+        - Question about the methodology or scoring
+    validations:
+      required: true
+  - type: textarea
+    id: change
+    attributes:
+      label: What should change
+      description: Name the field (for example `principles.open_governance.verdict` or `homepage_url`) and give the value you propose.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence
+      description: Links that support the change, such as a licence file, governance charter, changelog or adopters list.
+    validations:
+      required: true
+  - type: dropdown
+    id: relationship
+    attributes:
+      label: Your relationship to the specification
+      options:
+        - I am part of the maintaining organization
+        - I implement or use the specification
+        - Other
+    validations:
+      required: true

.github/workflows/check_specifications_data.yml

@@ -0,0 +1,33 @@
+name: Check specification registry data
+
+# Validates the files in data/ against the vocabularies in scripts/spec_data.py, so a
+# change to the registry is checked before it is merged.
+on:
+  pull_request:
+    paths:
+      - 'data/**'
+      - 'scripts/spec_data.py'
+      - 'scripts/check_specs.py'
+      - 'scripts/spec_api.py'
+  push:
+    branches:
+      - main
+    paths:
+      - 'data/**'
+      - 'scripts/spec_data.py'
+      - 'scripts/check_specs.py'
+      - 'scripts/spec_api.py'
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install PyYAML
+        run: pip install pyyaml
+      - name: Validate the registry files
+        run: python3 scripts/check_specs.py --export "$RUNNER_TEMP/export"

Makefile

@@ -10,14 +10,28 @@ setup:
 	pip3 install --force-reinstall -r requirements.txt && \
 	pip3 install --upgrade --force-reinstall mkdocs-material
 
+# --watch: mkdocs only watches docs/ and the config by itself, so the
+# specification registry's sources (hooks/, scripts/, data/) have to be named. Note that mkdocs caches
+# the hook module -- an edit to hooks/ or scripts/ triggers a rebuild but the
+# old code runs, so restart the server after changing those.
 serve: clean
 	@echo "Starting MkDocs server..."
 	@trap 'echo "Stopping MkDocs server..."; pkill -f "mkdocs serve"' SIGINT SIGTERM; \
-	mkdocs serve -f config/en/mkdocs.yml --dev-addr 127.0.0.1:8000 --watch overrides
+	mkdocs serve -f config/en/mkdocs.yml --dev-addr 127.0.0.1:8000 \
+		--watch overrides --watch hooks --watch scripts --watch data
 
 build: clean
 	mkdir -p generated  # Ensure the folder exists
 	mkdocs build -f config/en/mkdocs.yml --clean
 
 killserve:
 	pkill -f "mkdocs serve"
+
+# --- Specification registry (/specifications) -------------------------------
+# The pages and the /api/ files are built from data/ (see data/README.md).
+
+specs-check: ## Validate the registry files in data/ and print the display order
+	python3 scripts/check_specs.py
+
+specs-export: ## Write the API files (JSON catalogue, full export CSV) to generated/
+	python3 scripts/check_specs.py --export generated

README.md

@@ -29,6 +29,36 @@ Over 60 public and private signatories have committed to implementing the Princi
 - [VIA Metropolitan Transit San Antonio](https://www.viainfo.net/)
 - [Washington State Department of Transportation (WSDOT) Public Transportation Division](https://wsdot.wa.gov/)
 
+## Specification registry (`/specifications`)
+
+The `/specifications` page, one page per specification under
+`/specifications/<id>/`, and a read-only JSON API under `/api/` are generated
+at build time from the files in [`data/`](data/README.md). GitHub is the
+source of truth and the place to contribute: each specification and each
+organization is one Markdown file with YAML front matter, and "Suggest a
+change" on a specification's page opens that file in GitHub's editor.
+
+| Path | What it is |
+| --- | --- |
+| `data/specifications/<id>.md` | One specification: fields in front matter, then `# Description`. |
+| `data/organizations/<id>.md` | One organization, its role and a link to its logo. |
+| `data/principles.csv` | The criteria and what earns each verdict. |
+| `data/licences.csv` | The licence ids specifications may use. |
+| `data/README.md` | Every field and allowed value, the ranking, and the API. |
+| `scripts/spec_data.py` | Loads, validates and joins the files. |
+| `scripts/spec_api.py` | Builds the `/api/` files: catalogue, full records, export CSV, the OpenAPI description, and its Swagger UI page at `/api/docs/`. |
+| `scripts/check_specs.py` | `make specs-check`: validation, also run on every pull request. |
+| `hooks/specifications.py` | MkDocs hook that renders the pages and publishes the API. |
+
+```bash
+make specs-check    # validate the data; fails on any unknown value or key
+make specs-export   # write the API files to generated/api/
+make serve          # check the result
+```
+
+`make serve` caches the hook module, so restart the server after editing
+`hooks/` or `scripts/`: it rebuilds, but with the previous code.
+
 ## Building the site locally
 
 1. In Terminal, change the directory to one where you wish to build the site.

config/en/mkdocs.yml

@@ -20,6 +20,9 @@ theme:
   logo: assets/images/logo.png
   favicon: assets/images/favicon.png
 
+hooks:
+  - ../../hooks/specifications.py
+
 plugins:
   - search:
       lang: 
@@ -57,10 +60,12 @@ extra:
 extra_javascript:
   - https://unpkg.com/mermaid@8.5.0/dist/mermaid.min.js
   - assets/javascript/fix-md-search.js
+  - assets/javascript/specifications.js
 
 extra_css:
   - https://use.fontawesome.com/releases/v5.13.0/css/all.css
   - assets/stylesheets/additional.css
+  - assets/stylesheets/specifications.css
 
 markdown_extensions:
   - attr_list
@@ -117,6 +122,7 @@ nav:
     - Glossary: definitions.md
 
 not_in_nav: |
+  specifications/*
   admin_draft_review.md
   coalition.md
   cosignatories.md