[CHORE] Finalize schema reference docs as fully generated

.github/workflows/ci.yml

@@ -56,6 +56,12 @@ jobs:
       - name: Install NPM dependencies
         run: npm ci
 
+      - name: Generate schema markdown docs
+        uses: OvertureMaps/workflows/.github/actions/generate-schema-docs@faa3fa4bbe01d85dc2e2139ff1f74ce70feb7df9 # zizmor: ignore[stale-action-refs] - main
+        with:
+          output-dir: ${{ github.workspace }}/docs/schema/reference
+          schema-ref: 'main'
+
       - name: Build
         run: npm run build
 

.github/workflows/production_deploy_documentation.yml

@@ -6,8 +6,14 @@ on:
   push:
     branches: [main]
 
-  # Allow running from the actions tab
+  # Allow running from the actions tab, and lets the schema repo trigger a
+  # rebuild against a specific released schema version/tag.
   workflow_dispatch:
+    inputs:
+      schema-ref:
+        description: 'Schema repo ref (branch, tag, or SHA) to generate reference docs from.'
+        type: string
+        required: true
 
 concurrency:
   group: pages
@@ -39,6 +45,12 @@ jobs:
       - name: Install NPM dependencies
         run: npm ci --prefer-dedupe
 
+      - name: Generate schema markdown docs
+        uses: OvertureMaps/workflows/.github/actions/generate-schema-docs@faa3fa4bbe01d85dc2e2139ff1f74ce70feb7df9 # zizmor: ignore[stale-action-refs] - main
+        with:
+          output-dir: ${{ github.workspace }}/docs/schema/reference
+          schema-ref: ${{ inputs['schema-ref'] || 'main' }}
+
       - name: Build Docusaurus Pages 🔧
         run: npm run build
 

.github/workflows/staging_deploy.yaml

@@ -16,7 +16,6 @@ permissions:
 env:
   DOCS_PATH: docs
   PREVIEW_PATH: /${{ github.event.repository.name }}/pr/${{ github.event.number }}
-  PREVIEW_PATH_NO_AUTOGEN: /${{ github.event.repository.name }}/pr/${{ github.event.number }}-no-autogen
   STAGING_URL: https://staging.overturemaps.org
   SCHEMA_PREVIEW: false # Set to true to only publish Schema reference docs
   AWS_ROLE_ARN: arn:aws:iam::763944545891:role/pages-staging-oidc-overturemaps
@@ -32,8 +31,9 @@ jobs:
         run: |
           echo "::warning title=Staging deploy not supported for fork PRs::Staging previews are only available for PRs from branches within this repository, not forks. Please open your PR from a branch in OvertureMaps/docs."
 
-  build-auto-gen:
-    name: Build (auto-gen schema)
+  build:
+    # Branch ruleset set to this job name to require this status check
+    name: Build
     if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     needs: check-fork
@@ -75,44 +75,10 @@ jobs:
           path: build
           name: build-artifact
 
-  build-repo-schema:
-    # Branch ruleset set to this job name to require this status check
-    name: Build
-    if: github.event.pull_request.head.repo.full_name == github.repository
-    runs-on: ubuntu-latest
-    needs: check-fork
-    steps:
-      - name: Check out the main docs repo repository and build.
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
-      - name: Set up Node.js
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version-file: 'package.json'
-
-      - uses: lowlydba/sustainable-npm@31d51025884f424f58f22e4e6578178bb4e79632 # v3.0.0
-
-      - run: npm ci --omit=dev
-
-      - name: Build Docusaurus website (using existing /schema/reference files)
-        run: npm run build
-        env:
-          DOCUSAURUS_URL: ${{ env.STAGING_URL }}/
-          DOCUSAURUS_BASE_URL: ${{ env.PREVIEW_PATH_NO_AUTOGEN }}/
-          SCHEMA_PREVIEW: ${{ env.SCHEMA_PREVIEW }}
-
-      - name: Upload docs build as an artifact 📦
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          path: build
-          name: build-artifact-no-autogen
-
   deploy:
     name: Deploy
     runs-on: ubuntu-slim
-    needs: [check-fork, build-auto-gen, build-repo-schema]
+    needs: [check-fork, build]
     environment:
       name: staging
       url: ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH }}/index.html
@@ -127,58 +93,46 @@ jobs:
           role-to-assume: ${{ env.AWS_ROLE_ARN }}
           aws-region: ${{ env.AWS_REGION }}
 
-      - name: Download auto-gen artifact 📥
+      - name: Download build artifact 📥
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: build-artifact
-          path: build-autogen
-
-      - name: Download repo schema artifact 📥
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: build-artifact-no-autogen
-          path: build-no-autogen
+          path: build
 
       - name: Copy to S3
         run: |
-          aws s3 sync --delete --quiet build-autogen s3://overture-managed-staging-usw2/gh-pages${PREVIEW_PATH}/
-          aws s3 sync --delete --quiet build-no-autogen s3://overture-managed-staging-usw2/gh-pages${PREVIEW_PATH_NO_AUTOGEN}/
+          aws s3 sync --delete --quiet build s3://overture-managed-staging-usw2/gh-pages${PREVIEW_PATH}/
 
       - name: Bust the Cache
         run: |
-          aws cloudfront create-invalidation --distribution-id E1KP2IN0H2RGGT --paths "${PREVIEW_PATH}/*" "${PREVIEW_PATH_NO_AUTOGEN}/*"
+          aws cloudfront create-invalidation --distribution-id E1KP2IN0H2RGGT --paths "${PREVIEW_PATH}/*"
 
       - name: Gather metadata for PR comment
         id: deploy-metadata
         run: |
           echo "time=$(date -u +'%b %d, %Y %H:%M UTC')" >> $GITHUB_OUTPUT
           echo "short-sha=${PR_HEAD_SHA:0:7}" >> $GITHUB_OUTPUT
-          schema_ref="${NEEDS_BUILD_AUTO_GEN_OUTPUTS_SCHEMA_REF#refs/heads/}"
+          schema_ref="${NEEDS_BUILD_OUTPUTS_SCHEMA_REF#refs/heads/}"
           schema_ref="${schema_ref#refs/tags/}"
           echo "schema-ref-short=$schema_ref" >> $GITHUB_OUTPUT
-          echo "schema-short-sha=${NEEDS_BUILD_AUTO_GEN_OUTPUTS_SCHEMA_SHA:0:7}" >> $GITHUB_OUTPUT
+          echo "schema-short-sha=${NEEDS_BUILD_OUTPUTS_SCHEMA_SHA:0:7}" >> $GITHUB_OUTPUT
         env:
-          NEEDS_BUILD_AUTO_GEN_OUTPUTS_SCHEMA_REF: ${{ needs.build-auto-gen.outputs.schema-ref }}
-          NEEDS_BUILD_AUTO_GEN_OUTPUTS_SCHEMA_SHA: ${{ needs.build-auto-gen.outputs.schema-sha }}
+          NEEDS_BUILD_OUTPUTS_SCHEMA_REF: ${{ needs.build.outputs.schema-ref }}
+          NEEDS_BUILD_OUTPUTS_SCHEMA_SHA: ${{ needs.build.outputs.schema-sha }}
           PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
 
       - name: Comment on PR
         uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5
         with:
           message: |
-            ## 🗺️ OMF Docs previews are live!
+            ## 🗺️ Overture Docs preview is live!
 
             |                         |                                                                      |
             |-------------------------|----------------------------------------------------------------------|
-            | 🆕 **Auto-gen schema site (beta)**  | ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH }}/index.html           |
-            | 🗂️ **Auto-gen schema ref** | [${{ steps.deploy-metadata.outputs.schema-ref-short }}@${{ steps.deploy-metadata.outputs.schema-short-sha }}](https://github.com/OvertureMaps/schema/tree/${{ needs.build-auto-gen.outputs.schema-ref }}) |
-            | 🌍 **Repo schema site**      | ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH_NO_AUTOGEN }}/index.html |
+            | 🌍 **Preview site**     | ${{ env.STAGING_URL }}${{ env.PREVIEW_PATH }}/index.html            |
+            | 🗂️ **Schema ref**      | [${{ steps.deploy-metadata.outputs.schema-ref-short }}@${{ steps.deploy-metadata.outputs.schema-short-sha }}](https://github.com/OvertureMaps/schema/tree/${{ needs.build.outputs.schema-ref }}) |
             | 🕐 **Updated**          | ${{ steps.deploy-metadata.outputs.time }}                            |
             | 📝 **Commit**           | [${{ steps.deploy-metadata.outputs.short-sha }}](${{ github.server_url }}/${{ github.repository }}/commit/${{ github.event.pull_request.head.sha }}) |
 
-            Auto-gen schema site is now available. This is an early preview of a future workflow where we will automatically generate and publish reference docs for the Overture Maps Format schema.
-
-            The auto-gen schema site may contain incomplete or inaccurate information as we are still refining the generation process, so please compare against the repo schema site and refer to the official Overture documentation for authoritative information.
-
             > [!NOTE]
             > ♻️ This preview updates automatically with each push to this PR.

.gitignore

@@ -3,3 +3,7 @@
 node_modules/
 build/
 static/maplibre/
+
+# Schema reference docs are generated at build time by the
+# generate-schema-docs action; see docs/schema/index.md.
+docs/schema/reference/

README.md

@@ -15,11 +15,11 @@ This repository uses [Docusaurus](https://docusaurus.io/) to publish the documen
 
 ## Schema Reference (`docs.overturemaps.org/schema`)
 
-The Overture schema repository [github/overturemaps/schema](https://github.com/overturemaps/schema) maintains the official Overture schema and the documentation surrounding the actual schema reference pages. This is to ensure that the schema, documentation, and relevant examples are always in-sync.
+The Overture schema repository [OvertureMaps/schema](https://github.com/OvertureMaps/schema) maintains the official Overture schema as Pydantic models, and the reference pages under `docs.overturemaps.org/schema` are generated directly from those models. This keeps the schema and its documentation permanently in sync.
 
-The script `fetch_schema.sh` injects the contents of the schema's documentation into `docs/schema/` and copies the schema `YAML` files and examples to `docs/_schema` and `docs/_examples`, respectively. This script runs with every build.
+Every build (CI, PR preview, and production) runs the [`generate-schema-docs`](https://github.com/OvertureMaps/workflows/tree/main/.github/actions/generate-schema-docs) action, which generates Markdown into `docs/schema/reference/` from the schema repository's `main` branch (or a specific `schema-ref` when triggered via `workflow_dispatch`, e.g. from an `overture-schema` release). `docs/schema/reference/` is gitignored and never committed here.
 
-Therefore, anything available at `docs.overturemaps.org/schema` (under the **Schema Reference** link in the header) comes from the Overture schema repository, not this repository. Any changes to `schema` will be overwritten on every build.
+**If you spot a typo or error under `docs.overturemaps.org/schema`, it is not fixable in this repository.** Open an issue or PR against the docstrings/models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema) instead — any change here will be overwritten on the next build.
 
 ## Developing
 

docs/schema/index.md

@@ -17,6 +17,10 @@ The Overture Maps schema defines the structure, properties, and constraints for
 
 The schema is authored as [Pydantic](https://docs.pydantic.dev/) models and the reference documentation is generated from those models. The source code lives in the [OvertureMaps/schema](https://github.com/OvertureMaps/schema) repository on GitHub.
 
+:::tip[Found an error on this page?]
+This page is generated from the Pydantic models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema/issues). Please file an issue there for changes.
+:::
+
 ## Why Use Pydantic to Define Data Schemas?
 
 This project addresses a fundamental challenge in data consumption: bridging the semantic gap between raw data and human understanding while enabling machine-actionable workflows.