schema: Move schema files into a versioned folder (#636)

To prepare for future updates to the schema, we use a versioned folder.
Then downstream users, such as cli, can use the schema file from the
versioned folder(s) which the user understands. This will also allow
users to support and validate documents from older schema versions.

We also add the version property to the schema. This is supported by cli
from instructlab/instructlab#417. The version property
is not required for version 1.

---------

Signed-off-by: BJ Hargrave <hargrave@us.ibm.com>

Author: bjhargrave

.github/schemas/compositional_skills.json renamed to .github/schemas/v1/compositional_skills.json

@@ -2,12 +2,13 @@
     "title": "Compositional Skill",
     "description": "A compositional skill.",
     "type": "object",
+    "$ref": "./version.json",
     "required": [
         "created_by",
         "task_description",
         "seed_examples"
     ],
-    "additionalProperties": false,
+    "unevaluatedProperties": false,
     "properties": {
         "created_by": {
             "description": "The GitHub username of the contributor.",
@@ -30,7 +31,7 @@
                     "question",
                     "answer"
                 ],
-                "additionalProperties": false,
+                "unevaluatedProperties": false,
                 "properties": {
                     "context": {
                         "description": "Information that the model is expected to take into account during processing. This is different from knowledge, where the model is expected to gain facts and background knowledge from the tuning process.",

.github/schemas/knowledge.json renamed to .github/schemas/v1/knowledge.json

@@ -2,13 +2,14 @@
     "title": "Knowledge",
     "description": "A knowledge skill.",
     "type": "object",
+    "$ref": "./version.json",
     "required": [
         "created_by",
         "domain",
         "task_description",
         "seed_examples"
     ],
-    "additionalProperties": false,
+    "unevaluatedProperties": false,
     "properties": {
         "created_by": {
             "description": "The GitHub username of the contributor.",
@@ -36,7 +37,7 @@
                     "question",
                     "answer"
                 ],
-                "additionalProperties": false,
+                "unevaluatedProperties": false,
                 "properties": {
                     "question": {
                         "description": "A question used for synthetic data generation.",

.github/schemas/metadata.json renamed to .github/schemas/v1/metadata.json

@@ -2,10 +2,11 @@
     "title": "Taxonomy metadata",
     "description": "Accompanying metadata for a peer taxonomy file.",
     "type": "object",
+    "$ref": "./version.json",
     "required": [
         "seed_examples"
     ],
-    "additionalProperties": false,
+    "unevaluatedProperties": false,
     "properties": {
         "seed_examples": {
             "description": "An array of metadata for the seed examples in the peer taxonomy file.",
@@ -17,7 +18,7 @@
                     "source",
                     "license"
                 ],
-                "additionalProperties": false,
+                "unevaluatedProperties": false,
                 "properties": {
                     "source": {
                         "title": "Attribution Source",

.github/schemas/v1/version.json

@@ -0,0 +1,13 @@
+{
+    "title": "Taxonomy Document Schema Version",
+    "type": "object",
+    "$comment": "After version 1, the 'version' property must become required.",
+    "properties": {
+        "version": {
+            "description": "The schema version of the taxonomy document.",
+            "type": "integer",
+            "$comment": "This value must match the number in the containing folder.",
+            "const": 1
+        }
+    }
+}

.github/scripts/check-yaml.sh

@@ -18,15 +18,16 @@ if [ $# -lt 1 ]; then
     exit 1
 fi
 
-SCHEMAS="$(dirname ${BASH_SOURCE[0]})/../schemas"
+SCHEMA_VERSION=1
+SCHEMAS="$(dirname ${BASH_SOURCE[0]})/../schemas/v${SCHEMA_VERSION}"
 CHANGED_FILES="$@"
 ERR=0
 error() { printf "ERROR: %s: %s \"%s\"\n" "$1" "$2" "$3" 1>&2; ERR=1; }
 warn() { printf "WARN: %s: %s \"%s\"\n" "$1" "$2" "$3" 1>&2; }
 for file in ${CHANGED_FILES}; do
     case $file in 
       compositional_skills/*/qna.yaml)
-        eval "$(check-jsonschema --schemafile $SCHEMAS/compositional_skills.json -o JSON $file | jq -r '.errors[] | (.path | ltrimstr("$")) as $path | "\($path)|line" as $yqline | @sh "$(yq \($yqline) \(.filename))" as $yqcmd | @sh "\(.message[-200:])" as $message | "error \"\(.filename):\($yqcmd):1\" \"\($path)\" \($message)"')"
+        eval "$(check-jsonschema --schemafile $SCHEMAS/compositional_skills.json -o JSON $file | jq -r '.errors[] | (.path | ltrimstr("$") | select(. != "") // ".") as $path | "\($path)|line" as $yqline | @sh "$(yq \($yqline) \(.filename))" as $yqcmd | @sh "\(.message[-200:])" as $message | "error \"\(.filename):\($yqcmd):1\" \"\($path)\" \($message)"')"
         ;;
       knowledge/*)
         error "$file:1:1" "." "We do not accept knowledge PRs at this time"