ocpi.fyi

Multi-version Antora documentation site for OCPI specifications.

This repository mirrors official OCPI release branches into versioned folders under specifications/, keeps upstream Git history, and publishes a single documentation website with version switching.

Disclaimer: This is an unofficial, independent documentation site. It is not affiliated with or endorsed by the EVRoaming Foundation.

Goals

• Import OCPI versions from https://github.com/ocpi/ocpi
• Keep one folder per version: specifications/ocpi-x.y.z
• Preserve history for each imported version (for future sync)
• Generate a multi-version Antora site
• Deploy automatically to GitHub Pages
• Serve the site on ocpi.fyi

Upstream Sync Model (git subtree)

Each OCPI release branch is imported with git subtree, so commit history remains available inside each specifications/ocpi-x.y.z directory.

Configure upstream

git remote add upstream https://github.com/ocpi/ocpi.git
git fetch upstream

Initial imports

git subtree add --prefix specifications/ocpi-2.3.0 upstream release-2.3.0-bugfixes
git subtree add --prefix specifications/ocpi-2.2.1 upstream release-2.2.1-bugfixes
git subtree add --prefix specifications/ocpi-2.2.0 upstream release-2.2-bugfixes
git subtree add --prefix specifications/ocpi-2.1.1 upstream release-2.1.1-bugfixes

Resync an existing version

git fetch upstream
git subtree pull --prefix specifications/ocpi-2.3.0 upstream release-2.3.0-bugfixes

Target Structure

specifications/
  ocpi-2.3.0/
  ocpi-2.2.1/
  ocpi-2.2.0/
  ocpi-2.1.1/

Each version folder is treated as a versioned Antora content source.

Antora (multi-version)

The Antora playbook references all version folders and renders one site with version navigation. Each version includes Home, Spec, Library, Services, API Diff, Community, Sponsor, and About pages.

Version status

• 2.3.0: current release branch
• 2.2.1: stable maintained release
• 2.2.0: deprecated, replaced by 2.2.1
• 2.1.1: imported from upstream (Markdown-based source)

Typical local build:

npm install
npm run build:site

Generated site output is written to public/.

Conductor workspaces use a Git worktree, which Antora cannot consume directly as a local content source. Use the worktree-aware wrapper to build in a temporary standalone clone and copy the generated output back to public/:

npm run build:site:worktree

Site search (Pagefind)

• Search is powered by Pagefind.
• Search indexing is intentionally scoped to specification pages under /ocpi/.
• API pages under /api/ are not indexed.
• If a /ocpi/latest/ alias exists, it is excluded from indexing to avoid duplicate search results.
• Boilerplate UI text (for example Edit this Page) and module header boilerplate are excluded from search indexing.
• Search results display a version badge and support filtering by OCPI version in the search popup.

Useful commands:

npm run build:antora
npm run build:search

npm run build:site runs the full pipeline (Antora + API pages + search index).

Library section maintenance

• Library pages are generated per OCPI version.
• Active projects are grouped by technology.
• Inactive projects are listed in a dedicated Inactive Libraries section with a Language column.
• Planned/Partial support is shown as a warning in the Notes column.
• Last push dates are not displayed on public pages.
• Update workflow reference: ai/PLAN-library-catalog-workflow.md.

Services section maintenance

• Services pages are generated per OCPI version from data/services.csv.
• The catalog is non-exhaustive and informational (not an endorsement).
• Maintain source URLs and last_verified_date for each row.
• Use catalog_versions=all to publish a service on all version pages, or a version list like 2.3.0|2.2.1.
• Update workflow reference: ai/PLAN-services-catalog-workflow.md.

OpenAPI and API Reference

• OpenAPI sources are stored under openapi/ocpi-x.y.z
• An optional aggregate.json in a version directory customizes root metadata and excludes add-on modules from the generated core API
• Versioned Redoc pages are generated under public/api/<version>/
• OpenAPI diff pages are generated under public/api/<version>/diff/ (for configured baselines)
• Versioned Swagger UI pages are generated under public/api/<version>/swagger/
• /api/ redirects to the latest API version
• Each generated API page exposes Back to specification to /ocpi/<version>/index.html
• Public navigation labels and generated UI text are kept in English

Typical API build commands:

npm run test:openapi-invariants
npm run validate:openapi
npm run validate:openapi -- 2.3.0
npm run validate:openapi -- --changed
npm run build:redoc
npm run build:openapi-diff
npm run build:swagger

npm run validate:openapi uses the locally pinned Redocly, Spectral, and OpenAPI Generator versions. The optional version argument limits validation to one openapi/ocpi-x.y.z directory. Use --changed for a focused local check, --verbose for complete validator output, and --jobs <count> to control parallelism.

Intentional compatibility choices and deviations from the official OpenAPI repository are recorded by version in openapi/DECISIONS.md. Immutable upstream commits for each audited OCPI version are recorded in openapi/upstream-revisions.yaml. The complete maintainer workflow and command reference are available in openapi/MAINTENANCE.md.

Before publishing a branch, run npm run check:github to confirm its tracking branch, remote delta, worktree state, and current pull request.

Run npm run publish:pr -- --title "..." --body-file <path> after committing to push the branch, wait for GitHub to expose the new commit, and create the pull request. The script refuses dirty worktrees and verifies that the branch is ahead of main.

npm run build:swagger auto-detects every openapi/ocpi-x.y.z/ directory and generates one Swagger UI page per version.

Redoc, Swagger UI, and API Diff build from disposable aggregates under public/api/.cache; site builds do not rewrite tracked openapi.yaml files.

npm run build:site builds Antora + Redoc + Swagger UI and then generates the Pagefind index into public/.

OpenAPI release assets

• .github/workflows/openapi-release-draft.yml creates an immutable OpenAPI draft release from a manual trigger.
• The workflow creates the release tag, builds assets, creates a draft release, and attaches artifacts in one run.
• Release assets include one bundled OpenAPI file per version (openapi-<version>.yaml).
• Release assets include one OpenAPI source archive for all versions (openapi-all.zip) containing openapi/ocpi-<version>/ directories.

Deployment

GitHub Pages

• Build Antora in CI
• Upload public/ as Pages artifact
• Deploy with actions/deploy-pages

Notes

• Keep subtree imports additive and traceable.
• Do not rewrite imported subtree history.
• Use OCPI release branch names directly (for example, release-2.3.0-bugfixes).

Maintainer

• Maintained by Julien Herr
• Website: https://juherr.dev/
• Contact: ocpi@juherr.dev
• Source code: https://github.com/juherr/ocpi-doc