Validate _superseded_operations.yaml against its JSON schema (#276)

* Validate _superseded_operations.yaml against its JSON schema

Signed-off-by: Theo Truong <theotr@amazon.com>

* # lint

Signed-off-by: Theo Truong <theotr@amazon.com>

* # lint

Signed-off-by: Theo Truong <theotr@amazon.com>

---------

Signed-off-by: Theo Truong <theotr@amazon.com>

json_schemas/_superseded_operations.yaml

@@ -0,0 +1,20 @@
+$schema: http://json-schema.org/draft-07/schema#
+type: object
+patternProperties:
+  ^\$schema$:
+    type: string
+  ^/:
+    type: object
+    properties:
+      superseded_by:
+        type: string
+        pattern: ^/
+      operations:
+        type: array
+        items:
+          type: string
+          enum: [GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH]
+    required: [superseded_by, operations]
+    additionalProperties: false
+required: [$schema]
+additionalProperties: false

spec/_superseded_operations.yaml

@@ -1,3 +1,5 @@
+$schema: ../json_schemas/_superseded_operations.yaml
+
 /_opendistro/_alerting/destinations:
   superseded_by: /_plugins/_alerting/destinations
   operations:

tools/linter/SpecValidator.ts

@@ -4,16 +4,19 @@ import RootFile from './components/RootFile'
 import { type ValidationError } from '../types'
 import PathRefsValidator from './PathRefsValidator'
 import SchemaRefsValidator from './SchemaRefsValidator'
+import SupersededOperationsFile from './components/SupersededOperationsFile'
 
 export default class SpecValidator {
   root_file: RootFile
+  superseded_ops_files: SupersededOperationsFile
   namespaces_folder: NamespacesFolder
   schemas_folder: SchemasFolder
   path_refs_validator: PathRefsValidator
   schema_refs_validator: SchemaRefsValidator
 
   constructor (root_folder: string) {
     this.root_file = new RootFile(`${root_folder}/opensearch-openapi.yaml`)
+    this.superseded_ops_files = new SupersededOperationsFile(`${root_folder}/_superseded_operations.yaml`)
     this.namespaces_folder = new NamespacesFolder(`${root_folder}/namespaces`)
     this.schemas_folder = new SchemasFolder(`${root_folder}/schemas`)
     this.path_refs_validator = new PathRefsValidator(this.root_file, this.namespaces_folder)
@@ -26,11 +29,12 @@ export default class SpecValidator {
       ...this.namespaces_folder.validate(),
       ...this.schemas_folder.validate()
     ]
-    if (component_errors.length) return component_errors
+    if (component_errors.length > 0) return component_errors
 
     return [
       ...this.path_refs_validator.validate(),
-      ...this.schema_refs_validator.validate()
+      ...this.schema_refs_validator.validate(),
+      ...this.superseded_ops_files.validate()
     ]
   }
 }

tools/linter/components/SupersededOperationsFile.ts

@@ -0,0 +1,23 @@
+import FileValidator from './base/FileValidator'
+import ajv from 'ajv'
+import fs from 'fs'
+import YAML from 'yaml'
+import { type ValidationError } from '../../types'
+
+export default class SupersededOperationsFile extends FileValidator {
+  JSON_SCHEMA_PATH = '../json_schemas/_superseded_operations.yaml'
+
+  validate (): ValidationError[] {
+    return [
+      this.validate_json_schema()
+    ].filter(e => e) as ValidationError[]
+  }
+
+  validate_json_schema (): ValidationError | undefined {
+    const schema = YAML.parse(fs.readFileSync(this.JSON_SCHEMA_PATH, 'utf8'))
+    const validator = (new ajv()).compile(schema)
+    if (!validator(this.spec())) {
+      return this.error(`File content does not match JSON schema found in '${this.JSON_SCHEMA_PATH}':\n ${JSON.stringify(validator.errors, null, 2)}`)
+    }
+  }
+}

tools/merger/SupersededOpsGenerator.ts

@@ -9,6 +9,7 @@ export default class SupersededOpsGenerator {
   constructor (root_path: string) {
     const file_path = root_path + '/_superseded_operations.yaml'
     this.superseded_ops = YAML.parse(fs.readFileSync(file_path, 'utf8'))
+    delete this.superseded_ops.$schema
   }
 
   generate (spec: Record<string, any>): void {

tools/package.json

@@ -11,10 +11,12 @@
     "test": "jest"
   },
   "dependencies": {
+    "ajv": "^8.13.0",
     "@apidevtools/swagger-parser": "^10.1.0",
     "@types/lodash": "^4.14.202",
     "@types/node": "^20.10.3",
     "lodash": "^4.17.21",
+    "typescript": "^5.4.5",
     "ts-node": "^10.9.1",
     "yaml": "^2.3.4"
   },
@@ -30,7 +32,6 @@
     "eslint-plugin-promise": "^6.1.1",
     "globals": "^15.0.0",
     "jest": "^29.7.0",
-    "ts-jest": "^29.1.2",
-    "typescript": "^5.4.5"
+    "ts-jest": "^29.1.2"
   }
 }

tools/test/linter/SupersededOperationsFile.test.ts

@@ -0,0 +1,11 @@
+import SupersededOperationsFile from '../../linter/components/SupersededOperationsFile'
+
+test('validate()', () => {
+  const validator = new SupersededOperationsFile('./test/linter/fixtures/_superseded_operations.yaml')
+  expect(validator.validate()).toEqual([
+    {
+      file: 'fixtures/_superseded_operations.yaml',
+      message: "File content does not match JSON schema found in '../json_schemas/_superseded_operations.yaml':\n [\n  {\n    \"instancePath\": \"/~1hello~1world/operations/1\",\n    \"schemaPath\": \"#/patternProperties/%5E~1/properties/operations/items/enum\",\n    \"keyword\": \"enum\",\n    \"params\": {\n      \"allowedValues\": [\n        \"GET\",\n        \"POST\",\n        \"PUT\",\n        \"DELETE\",\n        \"HEAD\",\n        \"OPTIONS\",\n        \"PATCH\"\n      ]\n    },\n    \"message\": \"must be equal to one of the allowed values\"\n  }\n]"
+    }
+  ])
+})

tools/test/linter/fixtures/_superseded_operations.yaml

@@ -0,0 +1,7 @@
+$schema: ../../../../json_schemas/_superseded_operations.yaml
+
+/hello/world:
+  superseded_by: /goodbye/world
+  operations:
+    - GET
+    - CLEAN

tools/test/linter/fixtures/empty/_superseded_operations.yaml

@@ -0,0 +1 @@
+$schema: ../../../../../json_schemas/_superseded_operations.yaml