From 76a0857253e02d56e99f9bbd4e096b69ae6edee3 Mon Sep 17 00:00:00 2001
From: Gunnar Andersson <gunnar.andersson@mercedes-benz.com>
Date: Mon, 24 Jun 2024 15:35:31 +0200
Subject: [PATCH] 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 <gunnar.andersson@mercedes-benz.com>
---
 .github/workflows/create-new-release.yml | 19 ++++++++++---------
 ifex/schema/ifex_to_json_schema.py       |  3 ++-
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/create-new-release.yml b/.github/workflows/create-new-release.yml
index e107b68..f1b72b6 100644
--- a/.github/workflows/create-new-release.yml
+++ b/.github/workflows/create-new-release.yml
@@ -12,7 +12,7 @@
 # 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:
@@ -20,7 +20,7 @@ on:
       - master
 
 jobs:
-  deploy_json_schema:
+  create_release:
     if: "contains(github.event.head_commit.message, 'RELEASE-TAG')"
     runs-on: ubuntu-22.04
     steps:
@@ -39,11 +39,6 @@ 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"
@@ -51,7 +46,13 @@ jobs:
           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
index c81b675..50ea8bb 100644
--- 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": {