JSON schema generation: Add a description/version field

Custom fields are allowed in the json schema but here we use the semi-standard description field. We don't intend to repeat a long description of what IFEX Core IDL is here, but it can be used to indicate the schema version, which is defined using the release tag. It will be placed there by replacing TAG-PLACEHOLDER in CI. RELEASE-TAG: spec_v1.3 Signed-off-by: Gunnar Andersson <[email protected]>
gunnar-mb · Jun 24, 2024 · 76a0857 · 76a0857
1 parent dbb9a9c
commit 76a0857
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 10 deletions.
diff --git a/.github/workflows/create-new-release.yml b/.github/workflows/create-new-release.yml
@@ -12,15 +12,15 @@
 # 3) Push commit (possibly via a pull request)
 # 4) When pushed or merge to master, the release process will create the remote tag and the release
 
-name: Deploy JSON Schema and create release
+name: Create release tag and publish JSON Schema
 
 on:
   push:
     branches:
       - master
 
 jobs:
-  deploy_json_schema:
+  create_release:
     if: "contains(github.event.head_commit.message, 'RELEASE-TAG')"
     runs-on: ubuntu-22.04
     steps:
@@ -39,19 +39,20 @@ jobs:
       - name: Install IFEX module
         run: python setup.py develop
 
-      - name: Run JSON-Schema generator
-        run: |
-          python ifex/schema/ifex_to_json_schema.py >temp-schema
-          python ifex/schema/pretty_print_json.py temp-schema >ifex-core-idl-schema.json
-
       - name: Determine variables
         run: |
           echo "TAG=$(echo "${{ github.event.head_commit.message }}" | grep -E '^ *RELEASE-TAG' | awk '{print $2}')"  >> "$GITHUB_OUTPUT"
           echo "HASH=$(git rev-parse HEAD | cut -c 1-16)" >> "$GITHUB_OUTPUT"
           echo "SHORTHASH=$(git rev-parse HEAD | cut -c 1-10)" >> "$GITHUB_OUTPUT"
         id: vars
 
-      - name: Create Release of JSON Schema file
+      - name: Run JSON-Schema generator
+        run: |
+          python ifex/schema/ifex_to_json_schema.py >temp-schema
+          python ifex/schema/pretty_print_json.py temp-schema >ifex-core-idl-schema.json
+          sed -i 's/TAG-PLACEHOLDER/${{ steps.vars.outputs.TAG }}/' ifex-core-idl-schema.json
+
+      - name: Create a new release
         if: "contains(github.event.head_commit.message, 'RELEASE-TAG')"
         uses: actions/create-release@v1
         id: create_release
@@ -66,7 +67,7 @@ jobs:
         env:
           GITHUB_TOKEN: "${{ github.token }}"
 
-      - name: Upload Release Asset
+      - name: Upload JSON schema file as a release asset
         if: "contains(github.event.head_commit.message, 'RELEASE-TAG')"
         id: upload-release-asset
         uses: actions/upload-release-asset@v1

diff --git a/ifex/schema/ifex_to_json_schema.py b/ifex/schema/ifex_to_json_schema.py
@@ -168,7 +168,8 @@ def collect_type_info(t, collection={}, seen={}):
     # Then print JSON-schema
     print('''{
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "title": "IFEX Core IDL (YAML format)",
+    "title": "IFEX Core IDL (YAML format), version: TAG-PLACEHOLDER",
+    "description": "This file can be used to validate IFEX Core IDL files, which are normally written in YAML, not JSON.  The schema is not the source-of-truth but an artifact generated from the source-of-truth, so it should be consistent",
     "type": "object",
     "allOf": [ { "$ref": "#/definitions/AST" } ],
     "definitions": {