Add GitHub Pages schema explorer

Publish the FermentationJSON schema catalog through GitHub Pages and add an interactive JSON Schema Studio-based explorer. Build and deploy the site automatically from main while keeping the repository schemas and catalog as the authoritative source.

Author: GregRR

.github/workflows/pages.yml

@@ -0,0 +1,91 @@
+name: Deploy schema explorer
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/pages.yml"
+      - "schemas/**"
+      - "tools/schema-explorer/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out FermentationJSON
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: python -m pip install uv
+
+      - name: Validate FermentationJSON
+        run: |
+          uv sync --frozen
+          uv run pytest
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Check out JSON Schema Studio v0.9.1
+        uses: actions/checkout@v7
+        with:
+          repository: ioflux-org/studio-json-schema
+          ref: v0.9.1
+          path: .pages-vendor/json-schema-studio
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: .pages-vendor/json-schema-studio/package-lock.json
+
+      - name: Build JSON Schema Studio
+        working-directory: .pages-vendor/json-schema-studio
+        run: |
+          npm ci
+          npm run build -- --base=./
+
+      - name: Build FermentationJSON Pages site
+        run: |
+          python tools/schema-explorer/build_site.py \
+            --studio-dist .pages-vendor/json-schema-studio/dist \
+            --studio-license .pages-vendor/json-schema-studio/LICENSE \
+            --output _site
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site/
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -68,6 +68,14 @@ catalog.
 
 Passing JSON Schema validation establishes structural validity only. Full FermentationJSON conformance also includes semantic requirements that are not completely expressible in JSON Schema, such as reference integrity, scientific interpretation rules, compatibility preservation, and loss-reporting behavior.
 
+## Interactive schema explorer
+
+The repository's GitHub Pages workflow publishes and visualizes the current pre-release schema set at:
+
+`https://gregrr.github.io/fermentation-json/`
+
+The Pages site provides an interactive schema graph and a selector generated from the versioned schema catalog. Cataloged schemas are also published as raw JSON at their canonical `$id` paths. The site is rebuilt automatically from `main`; the repository schemas remain the authoritative source, and the published `0.1.0` schema set remains explicitly pre-release until promoted through the project's release process.
+
 ## Quantity model
 
 Every interoperable quantity has a canonical representation. A reported representation is optional but strongly recommended when the value originated from user input, an imported document, an instrument, a laboratory result, a product label, a publication, or another identifiable source.

tests/tools/test_schema_explorer_site.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+BUILD_SCRIPT = ROOT / "tools" / "schema-explorer" / "build_site.py"
+CATALOG_PATH = ROOT / "schemas" / "catalog.v0.1.0.json"
+
+spec = importlib.util.spec_from_file_location("schema_explorer_build_site", BUILD_SCRIPT)
+assert spec is not None and spec.loader is not None
+build_site_module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(build_site_module)
+
+
+def _fake_studio(tmp_path: Path) -> tuple[Path, Path]:
+    studio = tmp_path / "studio-dist"
+    (studio / "assets").mkdir(parents=True)
+    (studio / "assets" / "index-test.js").write_text("export {};\n", encoding="utf-8")
+    (studio / "index.html").write_text(
+        (
+            '<!doctype html><div id="root"></div>'
+            '<script type="module" crossorigin '
+            'src="/fermentation-json/studio/assets/index-test.js"></script>'
+        ),
+        encoding="utf-8",
+    )
+    license_path = tmp_path / "LICENSE"
+    license_path.write_text("MIT test license\n", encoding="utf-8")
+    return studio, license_path
+
+
+def test_pages_build_publishes_cataloged_schemas_at_canonical_paths(tmp_path: Path) -> None:
+    studio, license_path = _fake_studio(tmp_path)
+    output = tmp_path / "site"
+
+    build_site_module.build_site(studio, license_path, output)
+
+    catalog = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
+    version = catalog["version"]
+    for entry in catalog["schemas"]:
+        published = output / "schemas" / version / entry["path"]
+        assert published.read_bytes() == (ROOT / "schemas" / entry["path"]).read_bytes()
+
+
+def test_pages_launcher_and_studio_bootstrap_are_catalog_driven(tmp_path: Path) -> None:
+    studio, license_path = _fake_studio(tmp_path)
+    output = tmp_path / "site"
+
+    build_site_module.build_site(studio, license_path, output)
+
+    launcher = (output / "index.html").read_text(encoding="utf-8")
+    studio_index = (output / "studio" / "index.html").read_text(encoding="utf-8")
+
+    assert "FermentationJSON Schema Explorer" in launcher
+    assert "pre-release schema set 0.1.0" in launcher
+    assert "core/document.schema.json" in launcher
+    assert "ingredients/hop.schema.json" in launcher
+    assert "ioflux.schema.editor.content" in studio_index
+    assert "../schemas/0.1.0/${schemaPath}" in studio_index
+    assert 'await import("/fermentation-json/studio/assets/index-test.js")' in studio_index
+    assert '<script type="module" crossorigin src=' not in studio_index
+    assert (output / ".nojekyll").is_file()
+    assert (output / "third-party" / "json-schema-studio-MIT.txt").read_text(
+        encoding="utf-8"
+    ) == "MIT test license\n"

tools/schema-explorer/README.md

@@ -0,0 +1,19 @@
+# FermentationJSON schema explorer
+
+The public GitHub Pages site is built from the repository's versioned schema
+catalog and the tagged MIT-licensed JSON Schema Studio application.
+
+The repository schemas remain authoritative. The Pages build:
+
+1. validates the repository test suite;
+2. builds JSON Schema Studio from the pinned upstream tag;
+3. publishes every cataloged schema at the path implied by its canonical `$id`;
+4. generates a FermentationJSON schema selector from `schemas/catalog.v0.1.0.json`;
+5. preloads the selected schema into the unmodified Studio application; and
+6. deploys the resulting static site to GitHub Pages.
+
+JSON Schema Studio is not vendored into this repository. The deployment workflow
+checks out the pinned upstream release and includes its MIT license in the
+published site.
+
+The current integration targets JSON Schema Studio `v0.9.1`.