Merge pull request OpenSLO#129 from CRThaze/json-schema

Define OpenSLO Spec as JSON-Schema

Makefile

@@ -12,3 +12,11 @@ run/checks/spell-and-markdown:
 	yarn check-word-lists
 	yarn cspell --no-progress '**/**'
 	yarn markdownlint --ignore 'node_modules/' '**/*.md'
+
+.PHONY: install/checks/schema-validation
+install/checks/schema-validation:
+	cd schema-test && go mod download
+
+.PHONY: run/checks/schema-validation
+run/checks/schema-validation:
+	cd schema-test && go clean -testcache && go test .

cspell.json

@@ -1,27 +1,34 @@
 {
-    "version": "0.1",
-    "language": "en_US",
-    "dictionaries": [
-        "bash",
-        "companies",
-        "css",
-        "go",
-        "html",
-        "misc",
-        "softwareTerms"
-    ],
-    "ignorePaths": [
-        ".vscode/",
-        ".idea/",
-        "**/node_modules/**",
-        "**/*.lock",
-        "package.json"
-    ],
-    "allowCompoundWords": true,
-    "words": [
-        "Kubernetes",
-        "openslo",
-        "socio",
-        "tada"
-    ]
-}
+	"version": "0.1",
+	"language": "en_US",
+	"dictionaries": [
+		"bash",
+		"companies",
+		"css",
+		"go",
+		"html",
+		"misc",
+		"softwareTerms"
+	],
+	"ignorePaths": [
+		".vscode/",
+		".idea/",
+		"**/node_modules/**",
+		"**/*.lock",
+		"package.json",
+		"schema-test/spec-files",
+		"schema-test/vendor",
+		"schema-test/*.go",
+		"schema-test/go.mod",
+		"schema-test/go.sum"
+	],
+	"allowCompoundWords": true,
+	"words": [
+		"Kubernetes",
+		"mhdw",
+		"openslo",
+		"socio",
+		"struct",
+		"tada"
+	]
+}

schema-test/README.md

@@ -0,0 +1,99 @@
+# JSON-Schema Definitions Validation
+
+This Go package takes the JSON-Schema files defined under `../schemas/` and
+does both a meta-validation of the schema files directly, as well as tests
+using them to validate a number of example spec-files.
+
+## Install Dependencies
+
+`go mod download`
+
+## Run Tests
+
+`go test .`
+
+Changes to the JSON-Schema Files or the test files themselves will not
+invalidate the test-cache. So be sure to clear the test-cache yourself between
+runs.
+
+`go clean -testcache`
+
+## Adding Tests
+
+The existing tests are written to be easily extended to new cases and to
+validate multiple versions of the OpenSLO specification at once.
+
+### New Cases
+
+Add a new test struct to the test-table.
+
+```go
+  tests := []struct {
+    name    string
+    version apiVersion
+    files   []string
+    wantErr bool
+  }{
+    ...
+    {
+      name: "my new test", // Name for the test case.
+      version: v1, // apiVersion constant this test-case applies to.
+      files: []string{
+        "path/to/the/new/test/file/relative/to/the/version/directory",
+        "other/files/expected/to/cover/the/same/test/case/and/result",
+      },
+      wantErr: false, // Whether this case covers files that should fail validation.
+    }
+  }
+```
+
+Create any needed files for your test-case under `./spec-files/<version>/`.
+
+### New Schema Versions
+
+First copy the test documents.
+
+```bash
+cp -r spec-files/v1 spec-files/v2beta
+# After having copied these files be sure to:
+# - Update all the apiVersion fields to reference the new version.
+# - Make any other relevant changes to each file that should be valid to bring
+#   it in-line with the new version.
+```
+
+Add a new constant for the new version ID.
+
+```go
+type apiVersion string
+
+const (
+  v1 apiVersion = "v1"
+  v2beta apiVersion = "v2beta" // New constant.
+)
+```
+
+Add a new entry to the schemaVersions map.
+
+```go
+  schemaVersions := map[apiVersion]*gjs.Schema{
+    v1: nil,
+    v2beta: nil,
+  }
+```
+
+Duplicate and adjust the test-cases in the test-table.
+
+```go
+  tests := []struct {
+    name    string
+    version apiVersion
+    files   []string
+    wantErr bool
+  }{
+    ...
+    // Add the a copy of each existing test case from the prior version and
+    // make adjustments as needed.
+    // Be sure to add or remove any test-cases and test files relevant to the
+    // new version.
+  }
+```

schema-test/go.mod

@@ -0,0 +1,14 @@
+module github.com/OpenSLO/OpenSLO/schema-test
+
+go 1.18
+
+require (
+	github.com/xeipuuv/gojsonschema v1.2.0
+	sigs.k8s.io/yaml v1.3.0
+)
+
+require (
+	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
+	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+)

schema-test/go.sum

@@ -0,0 +1,20 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
+github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
+github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+sigs.k8s.io/yaml v1.3.0 h1:a2VclLzOGrwOHDiV8EfBGhvjHvP46CtW5j6POvhYGGo=
+sigs.k8s.io/yaml v1.3.0/go.mod h1:GeOyir5tyXNByN85N/dRIT9es5UQNerPYEKK56eTBm8=

schema-test/schema.go

@@ -0,0 +1 @@
+package schematest