@squiz/dx-json-schema-lib 1.2.13-alpha.0

package/lib/manifest/v1/v1.json

@@ -0,0 +1,362 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "ComponentManifest",
+    "additionalProperties": false,
+    "properties": {
+        "$schema": { "type": "string", "description": "the manifest schema version" },
+        "namespace": {
+            "type": "string",
+            "description": "Namesapce of the component",
+            "$ref": "#/definitions/name-pattern"
+        },
+        "name": { "type": "string", "description": "Name of the component", "$ref": "#/definitions/name-pattern" },
+        "displayName": { "type": "string", "description": "Display name of the component" },
+        "description": { "type": "string", "description": "Description of the component" },
+        "mainFunction": {
+            "type": "string",
+            "description": "Name of the main function to be executed at the root of the access url"
+        },
+        "icon": {
+            "$ref": "DxComponentIcons.json"
+        },
+        "version": {
+            "type": "string",
+            "description": "Semver version number",
+            "minLength": 5,
+            "maxLength": 14,
+            "pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$"
+        },
+        "environment": {
+            "type": "array",
+            "description": "an array of environmental variables needed to execute correctly. These variables are set through your local environment variables during testing or through the component set during production run time",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "$ref": "#/definitions/name-pattern",
+                        "description": "Environmental variable name"
+                    },
+                    "required": {
+                        "type": "boolean",
+                        "default": true
+                    }
+                },
+                "required": ["name"]
+            }
+        },
+        "staticFiles": {
+            "type": "object",
+            "properties": {
+                "locationRoot": {
+                    "type": "string",
+                    "description": "The location the system begins looking static files. All static files will be referenced from here."
+                }
+            },
+            "required": ["locationRoot"]
+        },
+        "functions": {
+            "type": "array",
+            "minItems": 0,
+            "items": {
+                "title": "ComponentFunction",
+                "description": "Component function definition, this object provides the runtime with input validation and what to execute",
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "$ref": "#/definitions/name-pattern",
+                        "description": "Function name, this will be used as part of the url to access this function"
+                    },
+                    "entry": {
+                        "type": "string",
+                        "description": "File path to the javascript file to execute. The file path must be relative to the manifest file and cannot be in a folder above the manifest file."
+                    },
+                    "input": {
+                        "$ref": "DxComponentInputSchema.json"
+                    },
+                    "output": {
+                        "oneOf": [
+                            {
+                                "title": "HtmlResponse",
+                                "type": "object",
+                                "additionalProperties": false,
+                                "description": "The HtmlResponse type is for returning html content. The response out of the function must be a string. This response object also includes references to resources (staticFiles) the component needs to execute correctly. It is up to the integrating system to respect this.",
+                                "properties": {
+                                    "responseType": { "const": "html" },
+                                    "staticFiles": {
+                                        "type": "array",
+                                        "description": "A list of static resources that are required for the component to execute correctly",
+                                        "items": {
+                                            "type": "object",
+                                            "title": "HtmlStaticFile",
+                                            "additionalProperties": false,
+                                            "properties": {
+                                                "location": {
+                                                    "description": "The location property is used to inform integrating system if the static resource should be included in the header of footer of the document",
+                                                    "oneOf": [
+                                                        {
+                                                            "const": "header"
+                                                        },
+                                                        {
+                                                            "const": "footer"
+                                                        }
+                                                    ]
+                                                },
+                                                "file": {
+                                                    "oneOf": [
+                                                        {
+                                                            "type": "object",
+                                                            "title": "JsFile",
+                                                            "additionalProperties": false,
+                                                            "properties": {
+                                                                "type": {
+                                                                    "const": "js"
+                                                                },
+                                                                "filepath": {
+                                                                    "type": "string"
+                                                                },
+                                                                "defer": {
+                                                                    "type": "boolean"
+                                                                },
+                                                                "async": {
+                                                                    "type": "boolean"
+                                                                },
+                                                                "integrity": {
+                                                                    "type": "string"
+                                                                },
+                                                                "crossorigin": {
+                                                                    "oneOf": [
+                                                                        {
+                                                                            "const": "anonymous"
+                                                                        },
+                                                                        {
+                                                                            "const": "use-credentials"
+                                                                        }
+                                                                    ]
+                                                                },
+                                                                "referrerpolicy": {
+                                                                    "oneOf": [
+                                                                        {
+                                                                            "const": "no-referrer"
+                                                                        },
+                                                                        {
+                                                                            "const": "no-referrer-when-downgrade"
+                                                                        },
+                                                                        {
+                                                                            "const": "origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "origin-when-cross-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "same-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "strict-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "strict-origin-when-cross-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "unsafe-url"
+                                                                        }
+                                                                    ]
+                                                                }
+                                                            },
+                                                            "required": ["filepath", "type"]
+                                                        },
+                                                        {
+                                                            "type": "object",
+                                                            "title": "CssFile",
+                                                            "additionalProperties": false,
+                                                            "properties": {
+                                                                "type": {
+                                                                    "const": "css"
+                                                                },
+                                                                "filepath": {
+                                                                    "type": "string"
+                                                                },
+                                                                "crossorigin": {
+                                                                    "oneOf": [
+                                                                        {
+                                                                            "const": "anonymous"
+                                                                        },
+                                                                        {
+                                                                            "const": "use-credentials"
+                                                                        }
+                                                                    ]
+                                                                },
+                                                                "referrerpolicy": {
+                                                                    "oneOf": [
+                                                                        {
+                                                                            "const": "no-referrer"
+                                                                        },
+                                                                        {
+                                                                            "const": "no-referrer-when-downgrade"
+                                                                        },
+                                                                        {
+                                                                            "const": "origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "origin-when-cross-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "same-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "strict-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "strict-origin-when-cross-origin"
+                                                                        },
+                                                                        {
+                                                                            "const": "unsafe-url"
+                                                                        }
+                                                                    ]
+                                                                }
+                                                            },
+                                                            "required": ["filepath"]
+                                                        }
+                                                    ]
+                                                }
+                                            },
+                                            "required": ["location", "file"]
+                                        }
+                                    },
+                                    "headers": {
+                                        "title": "ResponseHeaders",
+                                        "type": "object",
+                                        "description": "Response headers to set",
+                                        "additionalProperties": {
+                                            "type": "string"
+                                        }
+                                    }
+                                },
+                                "required": ["responseType"]
+                            },
+                            {
+                                "title": "JsonResponse",
+                                "type": "object",
+                                "additionalProperties": false,
+                                "properties": {
+                                    "responseType": { "const": "json" },
+                                    "definition": { "$ref": "http://json-schema.org/draft-07/schema#" },
+                                    "headers": {
+                                        "title": "ResponseHeaders",
+                                        "type": "object",
+                                        "description": "Response headers to set",
+                                        "additionalProperties": {
+                                            "type": "string"
+                                        }
+                                    }
+                                },
+                                "required": ["responseType", "definition"]
+                            }
+                        ]
+                    }
+                },
+                "required": ["name", "entry", "input", "output"]
+            }
+        },
+        "previews": {
+            "type": "object",
+            "description": "A map of previews which provide configuration to preview the component in isolation",
+            "propertyNames": {
+                "$ref": "#/definitions/name-pattern"
+            },
+            "minProperties": 1,
+            "additionalProperties": {
+                "title": "Preview Definition",
+                "type": "object",
+                "description": "Name for the preview and how it will be accessed",
+                "required": ["functionData"],
+                "properties": {
+                    "functionData": {
+                        "description": "A map of the functions to their respective preview information. Properties must match name of a function defined in functions list",
+                        "type": "object",
+                        "propertyNames": {
+                            "$ref": "#/definitions/name-pattern"
+                        },
+                        "minProperties": 1,
+                        "additionalProperties": {
+                            "type": "object",
+                            "title": "Function preview configuration",
+                            "description": "Data inputs for the preview of functions in the component",
+                            "properties": {
+                                "inputData": {
+                                    "type": "object",
+                                    "description": "Property for defining the input data for this preview component function",
+                                    "properties": {
+                                        "type": {
+                                            "description": "An enum of 'file' or 'inline' for how the input data is defined",
+                                            "enum": ["file", "inline"]
+                                        }
+                                    },
+                                    "required": ["type"],
+                                    "oneOf": [
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "type": {
+                                                    "enum": ["file"]
+                                                },
+                                                "path": {
+                                                    "type": "string",
+                                                    "format": "uri-reference",
+                                                    "description": "Path to input data file"
+                                                }
+                                            },
+                                            "required": ["type", "path"]
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "type": {
+                                                    "enum": ["inline"]
+                                                },
+                                                "value": {
+                                                    "type": "object",
+                                                    "description": "Input data value"
+                                                }
+                                            },
+                                            "required": ["type", "value"]
+                                        }
+                                    ]
+                                },
+                                "headers": {
+                                    "title": "ResponseHeaders",
+                                    "type": "object",
+                                    "description": "Response headers to set",
+                                    "additionalProperties": {
+                                        "type": "string"
+                                    }
+                                },
+                                "wrapper": {
+                                    "type": "object",
+                                    "description": "Define the extra static files which provide a container for the component function",
+                                    "properties": {
+                                        "path": {
+                                            "type": "string",
+                                            "format": "uri-reference",
+                                            "description": "File path to the wrapper container"
+                                        }
+                                    },
+                                    "required": ["path"]
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "required": ["name", "namespace", "displayName", "description", "version", "functions", "$schema", "mainFunction"],
+    "definitions": {
+        "name-pattern": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_\\-]+$"
+        }
+    }
+}

package/lib/manifest/v1/v1.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/manifest/v1/v1.spec.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const SchemaValidationError_1 = require("../../errors/SchemaValidationError");
+const JsonValidationService_1 = require("../../JsonValidationService");
+async function fetchTestManifest(filename) {
+    const contents = await (0, promises_1.readFile)((0, path_1.resolve)(__dirname, '__test__', 'schemas', filename), {
+        encoding: 'utf-8',
+    });
+    return JSON.parse(contents);
+}
+describe('manifest/v1', () => {
+    let validationService;
+    beforeAll(() => {
+        validationService = new JsonValidationService_1.JsonValidationService();
+    });
+    it('succeeds on a valid manifest', async () => {
+        const manifest = await fetchTestManifest('validComponent.json');
+        expect(validationService.validateManifest(manifest, 'v1')).toBeTruthy();
+    });
+    it('errors on invalid property types in function input', async () => {
+        const manifest = await fetchTestManifest('badFunctionInputComponent.json');
+        expect(() => validationService.validateManifest(manifest, 'v1')).toThrowError(SchemaValidationError_1.SchemaValidationError);
+    });
+    it('errors on invalid property types in nested function input', async () => {
+        const manifest = await fetchTestManifest('badNestedFunctionInput.json');
+        expect(() => validationService.validateManifest(manifest, 'v1')).toThrowError(SchemaValidationError_1.SchemaValidationError);
+    });
+    it('errors on non-object top level input', async () => {
+        const manifest = await fetchTestManifest('nonObjectFunctionInputComponent.json');
+        expect(() => validationService.validateManifest(manifest, 'v1')).toThrowError(SchemaValidationError_1.SchemaValidationError);
+    });
+});
+//# sourceMappingURL=v1.spec.js.map

package/lib/manifest/v1/v1.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.spec.js","sourceRoot":"","sources":["../../../src/manifest/v1/v1.spec.ts"],"names":[],"mappings":";;AAAA,0CAAuC;AACvC,+BAA+B;AAC/B,8EAA2E;AAC3E,uEAAoE;AAEpE,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IAC/C,MAAM,QAAQ,GAAG,MAAM,IAAA,mBAAQ,EAAC,IAAA,cAAO,EAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE;QACnF,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,IAAI,iBAAwC,CAAC;IAE7C,SAAS,CAAC,GAAG,EAAE;QACb,iBAAiB,GAAG,IAAI,6CAAqB,EAAE,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;QAC5C,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,qBAAqB,CAAC,CAAC;QAChE,MAAM,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAC1E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,gCAAgC,CAAC,CAAC;QAC3E,MAAM,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,6CAAqB,CAAC,CAAC;IACvG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;QACxE,MAAM,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,6CAAqB,CAAC,CAAC;IACvG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;QACpD,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,sCAAsC,CAAC,CAAC;QACjF,MAAM,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,6CAAqB,CAAC,CAAC;IACvG,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@squiz/dx-json-schema-lib",
+  "version": "1.2.13-alpha.0",
+  "description": "",
+  "main": "lib/index.js",
+  "scripts": {
+    "compile": "tsc",
+    "precompile": "ts-node jsonCompiler.ts",
+    "lint": "eslint ./src --ext .ts",
+    "test": "jest -c jest.config.ts",
+    "test:update-snapshots": "jest -c jest.config.ts --updateSnapshot",
+    "clean": "rimraf \"tsconfig.tsbuildinfo\" \"./lib\""
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/express": "4.17.14",
+    "@types/jest": "28.1.8",
+    "@types/node": "17.0.27",
+    "dotenv": "16.0.3",
+    "eslint": "8.22.0",
+    "jest": "28.1.3",
+    "json-schema-to-typescript": "11.0.2",
+    "rimraf": "3.0.2",
+    "ts-jest": "28.0.8",
+    "ts-loader": "9.3.1",
+    "ts-node": "10.9.1",
+    "typescript": "4.9.3"
+  },
+  "dependencies": {
+    "ajv": "8.11.2",
+    "ajv-formats": "2.1.1",
+    "better-ajv-errors": "1.2.0"
+  },
+  "gitHead": "811fbf59292dd00a2051036f1115cba5781828dd"
+}

package/src/JsonValidationService.spec.ts

@@ -0,0 +1,162 @@
+import { JsonValidationService } from './JsonValidationService';
+import { SchemaValidationError } from './errors/SchemaValidationError';
+
+import validManifest from './manifest/v1/__test__/schemas/validComponent.json';
+
+describe('JsonValidationService', () => {
+  let jsonValidationService: JsonValidationService;
+  beforeEach(() => {
+    jsonValidationService = new JsonValidationService();
+  });
+
+  describe('validateManifest', () => {
+    it('should return true for a valid manifest', () => {
+      const result = jsonValidationService.validateManifest(validManifest, 'v1');
+      expect(result).toBe(true);
+    });
+
+    it('should throw a SchemaValidationError for an invalid manifest', () => {
+      const invalidManifest = { ...validManifest };
+
+      delete (invalidManifest as any).name;
+
+      expect(() => {
+        jsonValidationService.validateManifest(invalidManifest, 'v1');
+      }).toThrow(SchemaValidationError);
+      expect(() => {
+        jsonValidationService.validateManifest(invalidManifest, 'v1');
+      }).toMatchInlineSnapshot(`[Function]`);
+    });
+
+    it('should throw an error for an invalid manifest version', () => {
+      expect(() => {
+        jsonValidationService.validateManifest(validManifest, 'invalid-version' as any);
+      }).toThrow(Error);
+    });
+  });
+
+  describe('validateContentSchema', () => {
+    it('should return true for a valid content schema', () => {
+      const contentSchema = {
+        type: 'object',
+
+        properties: {
+          'my-input': { type: 'number' },
+        },
+
+        required: ['my-input'],
+      };
+      const result = jsonValidationService.validateContentSchema(contentSchema);
+      expect(result).toBe(true);
+    });
+
+    // TODO DEVX-658
+    it.skip('should return false for an invalid content schema, where the required property is missed from a child object', () => {
+      const contentSchema = {
+        type: 'object',
+
+        properties: {
+          'my-input': {
+            type: 'object',
+
+            properties: {
+              'my-deep-input': { type: 'object' },
+            },
+          },
+        },
+
+        required: ['my-input'],
+      };
+      expect(() => {
+        jsonValidationService.validateContentSchema(contentSchema);
+      }).toThrow(SchemaValidationError);
+    });
+
+    it('should throw a SchemaValidationError for an invalid content schema, top level type must be object', () => {
+      const contentSchema = {
+        type: 'array',
+
+        items: {
+          type: 'object',
+          properties: {
+            'my-input': { type: 'number' },
+          },
+          required: ['my-input'],
+        },
+      };
+      expect(() => {
+        jsonValidationService.validateContentSchema(contentSchema);
+      }).toThrow(SchemaValidationError);
+    });
+
+    // TODO DEVX-658
+    it.skip('should throw a SchemaValidationError for an invalid content schema missing the required property', () => {
+      const contentSchema = {
+        type: 'object',
+
+        properties: {
+          'my-input': { type: 'number' },
+        },
+      };
+      expect(() => {
+        jsonValidationService.validateContentSchema(contentSchema);
+      }).toThrow(SchemaValidationError);
+    });
+  });
+
+  describe('validateComponentInput', () => {
+    const functionInputSchema = {
+      type: 'object',
+
+      properties: {
+        'my-input': { type: 'number' },
+      },
+
+      required: ['my-input'],
+    };
+
+    it('should return true for valid input values', () => {
+      const inputValue = {
+        'my-input': 123,
+      };
+      const result = jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      expect(result).toBe(true);
+    });
+
+    it('should throw a SchemaValidationError for invalid input type', () => {
+      const inputValue = {
+        'my-input': '123',
+      };
+      expect(() => {
+        jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      }).toThrow(SchemaValidationError);
+      expect(() => {
+        jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      }).toMatchInlineSnapshot(`[Function]`);
+    });
+
+    it('should throw a SchemaValidationError for invalid input missing properties', () => {
+      const inputValue = {};
+      expect(() => {
+        jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      }).toThrow(SchemaValidationError);
+      expect(() => {
+        jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      }).toMatchInlineSnapshot(`[Function]`);
+    });
+
+    // TODO DEVX-658
+    it.skip('should throw a SchemaValidationError for invalid input additional properties', () => {
+      const inputValue = {
+        'my-input': 123,
+        'my-input-2': 123,
+      };
+      expect(() => {
+        jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      }).toThrow(SchemaValidationError);
+      expect(() => {
+        jsonValidationService.validateComponentInput(functionInputSchema, inputValue);
+      }).toMatchInlineSnapshot();
+    });
+  });
+});

package/src/JsonValidationService.ts

@@ -0,0 +1,54 @@
+import Ajv, { AnySchemaObject, SchemaObject } from 'ajv';
+import addFormats from 'ajv-formats';
+import betterAjvErrors from 'better-ajv-errors';
+
+import DxComponentInputSchema from './manifest/v1/DxComponentInputSchema.json';
+import DxComponentIcons from './manifest/v1/DxComponentIcons.json';
+import DxContentMetaSchema from './manifest/v1/DxContentMetaSchema.json';
+import v1 from './manifest/v1/v1.json';
+import { SchemaValidationError } from './errors/SchemaValidationError';
+
+export class JsonValidationService {
+  ajv: Ajv;
+  constructor() {
+    this.ajv = new Ajv({
+      strict: true,
+      schemas: { DxContentMetaSchema, v1, DxComponentIcons, DxComponentInputSchema },
+      allowUnionTypes: true,
+      allErrors: true,
+      formats: {
+        'multi-line': true,
+      },
+    });
+
+    addFormats(this.ajv);
+  }
+  validateManifest(manifest: unknown, version: 'v1') {
+    switch (version) {
+      case 'v1':
+        return this.doValidate(v1, manifest);
+
+      default:
+        throw new Error('Invalid manifest version');
+    }
+  }
+
+  validateContentSchema(contentSchema: AnySchemaObject) {
+    // This schema matches the input definition in the manifest
+    return this.doValidate(DxComponentInputSchema, contentSchema);
+  }
+
+  validateComponentInput(functionInputSchema: SchemaObject, inputValue: unknown) {
+    return this.doValidate(functionInputSchema, inputValue);
+  }
+
+  private doValidate(schema: string | SchemaObject, value: unknown): true {
+    const result = this.ajv.validate(schema, value);
+    if (!result) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const betterErrors = betterAjvErrors(schema, value, this.ajv.errors!, { format: 'js' });
+      throw new SchemaValidationError(betterErrors);
+    }
+    return result;
+  }
+}