RFC 0005: schema version signals (v1.4.0)

.github/workflows/release-spec.yml

@@ -123,6 +123,23 @@ jobs:
           cp schema/v1.json dist/schema/v1.json
           echo "Published schema/v1.json -> dist/schema/v1.json (canonical \$id)"
 
+      # Assemble /schema/versions.json from the v* schema dirs already on gh-pages
+      # plus the current tag. gh-pages deploys with keep_files:true, so prior
+      # versions persist; we read them back to build the full list. On a manual
+      # run (no tag) VERSION is a branch name and gets filtered out by the
+      # generator's semver check, leaving the manifest built from existing dirs.
+      - name: Publish versions manifest (Step A3)
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          mkdir -p dist/schema
+          git fetch origin gh-pages --depth=1 || true
+          EXISTING=$(git ls-tree -r origin/gh-pages --name-only 2>/dev/null \
+            | grep -oE '^v[0-9]+\.[0-9]+\.[0-9]+/ocf-action-v1.json' \
+            | sed 's#/ocf-action-v1.json##' | sort -u | tr '\n' ' ')
+          node scripts/build-versions-manifest.mjs "$EXISTING" "$VERSION" > dist/schema/versions.json
+          echo "Published versions.json:"; cat dist/schema/versions.json
+
       - name: Deploy to gh-pages (Step C)
         uses: peaceiris/actions-gh-pages@v4
         with:

README.md

@@ -3,7 +3,7 @@
 **An open standard for representing team-sport coaching diagrams, drill animations, and playbooks as structured data — for invasion team sports, basketball first.**
 
 [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
-[![Schema Version](https://img.shields.io/badge/schema-v1.3.0-blue)](schema/v1.json)
+[![Schema Version](https://img.shields.io/badge/schema-v1.4.0-blue)](schema/v1.json)
 [![Status: Draft](https://img.shields.io/badge/status-draft-yellow)]()
 
 ---

docs/specification-v1.adoc

@@ -1,5 +1,5 @@
 = Open Coaching Format — Open Standard for Team-Sport Coaching Diagrams
-:version: 1.3.0
+:version: 1.4.0
 :doctype: book
 :toc: left
 :toc-title: Table of Contents
@@ -1144,6 +1144,20 @@ is the derivative. A single optional reference (not an array).
 }
 ----
 
+=== `meta.min_schema_version`
+
+`min_schema_version` (optional, SemVer) declares the minimum schema version
+needed to validate the document correctly. Set it when the document uses a field
+introduced in a specific minor, so a validator whose bundled schema is older can
+warn that it may be out of date rather than reporting the newer fields as errors.
+Omit it otherwise. It never changes how a current validator validates a document
+— it is a signal for version-skew diagnostics.
+
+[source,json]
+----
+"meta": { "id": "...", "title": "...", "min_schema_version": "1.4.0" }
+----
+
 ---
 
 == Schema Reference
@@ -1181,6 +1195,7 @@ class Meta {
   +difficulty: enum?
   +created: datetime?
   +source_format: enum?
+  +min_schema_version: semver?
 }
 
 class Court {
@@ -1444,6 +1459,13 @@ npx ajv-cli validate \
 [appendix]
 == Changelog
 
+=== v1.4.0
+
+Adds schema version signals (RFC 0005): optional `min_schema_version` in `meta`,
+a machine-readable `x-ocf-version` keyword, and a published `versions.json`
+manifest. All additive and backwards-compatible; documents without the new field
+are unchanged.
+
 === v1.3.0
 
 Adds optional `side` (`left`/`right`) and `arc` (`tight`/`normal`/`wide`) fields