Merge pull request #7 from cloudflare/merge

Adds $merge support

Author: celso

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2] - 2025-03-07
+
+### Added
+
+- $merge support - see README for more information
+
 ## [0.1.1] - 2025-02-26
 
 ### Added

README.md

@@ -71,6 +71,8 @@ Cabidela takes a JSON-Schema and optional configuration flags:
 - `applyDefaults`: boolean - If true, the validator will apply default values to the input object. Default is false.
 - `errorMessages`: boolean - If true, the validator will use custom `errorMessage` messages from the schema. Default is false.
 - `fullErrors`: boolean - If true, the validator will be more verbose when throwing errors for complex schemas (example: anyOf, oneOf's), set to false for shorter exceptions. Default is true.
+- `useMerge`: boolean - Set to true if you want to use the `$merge` keyword. Default is false. See below for more information.
+- `subSchema`: any[] - An optional array of sub-schemas that can be used with `$id` and `$ref`. See below for more information.
 
 Returns a validation object.
 
@@ -249,6 +251,49 @@ cabidela.validate({
 });
 ```
 
+## Combined schemas and $merge
+
+The standard way of combining and extending schemas is by using the [`allOf`](https://json-schema.org/understanding-json-schema/reference/combining#allOf) (AND), [`anyOf`](https://json-schema.org/understanding-json-schema/reference/combining#anyOf) (OR), [`oneOf`](https://json-schema.org/understanding-json-schema/reference/combining#oneOf) (XOR) and [`not`](https://json-schema.org/understanding-json-schema/reference/combining#not) keywords, all supported by this library.
+
+Cabidela supports an additional keyword `$merge` (inspired by [Ajv](https://ajv.js.org/guide/combining-schemas.html#merge-and-patch-keywords)) that allows you to merge two objects. This is useful when you want to extend a schema with additional properties and `allOf`` is not enough.
+
+Here's how it works:
+
+```json
+{
+  "$merge": {
+    "source": {
+      "type": "object",
+      "properties": { "p": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "with": {
+      "properties": { "q": { "type": "number" } }
+    }
+  }
+}
+```
+
+Resolves to:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "q": {
+      "type": "number"
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+To use `$merge` set the `useMerge` flag to true when creating the instance.
+
+```js
+new Cabidela(schema, { useMerge: true });
+```
+
 ## Custom errors
 
 If the new instance options has the `errorMessages` flag set to true, you can use the property `errorMessage` in the schema to define custom error messages.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/cabidela",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Cabidela is a small, fast, eval-less, Cloudflare Workers compatible, dynamic JSON Schema validator",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -27,6 +27,9 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "prettier": {
+    "embeddedLanguageFormatting": "auto"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/cabidela.git"
@@ -39,6 +42,7 @@
     "@vitest/ui": "^3.0.3",
     "ajv": "^8.17.1",
     "ajv-errors": "^3.0.0",
+    "ajv-merge-patch": "^5.0.1",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.0.3"

src/helpers.ts

@@ -1,3 +1,5 @@
+import type { CabidelaOptions } from ".";
+
 export type metaData = {
   types: Set<string>;
   size: number;
@@ -21,24 +23,50 @@ export const parse$ref = (ref: string) => {
   return { $id, $path };
 };
 
-export const traverseSchema = (definitions: any, obj: any, cb: any = () => {}) => {
-  Object.keys(obj).forEach((key) => {
-    if (obj[key] !== null && typeof obj[key] === "object") {
-      traverseSchema(definitions, obj[key], (value: any) => {
-        obj[key] = value;
-      });
-    } else {
-      if (key === "$ref") {
-        const { $id, $path } = parse$ref(obj[key]);
-        const { resolvedObject } = resolvePayload($path, definitions[$id]);
-        if (resolvedObject) {
-          cb(resolvedObject);
-        } else {
-          throw new Error(`Could not resolve '${obj[key]}' $ref`);
+function deepMerge(target: any, source: any) {
+  const result = Array.isArray(target) && Array.isArray(source) ? target.concat(source) : { ...target, ...source };
+  for (const key of Object.keys(result)) {
+    result[key] =
+      typeof target[key] == "object" && typeof source[key] == "object"
+        ? deepMerge(target[key], source[key])
+        : structuredClone(result[key]);
+  }
+  return result;
+}
+
+export const traverseSchema = (options: CabidelaOptions, definitions: any, obj: any, cb?: any) => {
+  let hits: number;
+  do {
+    hits = 0;
+    Object.keys(obj).forEach((key) => {
+      if (obj[key] !== null && typeof obj[key] === "object") {
+        traverseSchema(options, definitions, obj[key], (value: any) => {
+          hits++;
+          obj[key] = value;
+        });
+        if (options.useMerge && key === "$merge") {
+          const merge = deepMerge(obj[key].source, obj[key].with);
+          if (cb) {
+            cb(merge);
+          } else {
+            // root level merge
+            Object.assign(obj, merge);
+            delete obj[key];
+          }
+        }
+      } else {
+        if (key === "$ref") {
+          const { $id, $path } = parse$ref(obj[key]);
+          const { resolvedObject } = resolvePayload($path, definitions[$id]);
+          if (resolvedObject) {
+            cb(resolvedObject);
+          } else {
+            throw new Error(`Could not resolve '${obj[key]}' $ref`);
+          }
         }
       }
-    }
-  });
+    });
+  } while (hits > 0);
 };
 
 /* Resolves a path in an object

src/index.ts

@@ -2,6 +2,7 @@ import { resolvePayload, pathToString, traverseSchema } from "./helpers";
 
 export type CabidelaOptions = {
   applyDefaults?: boolean;
+  useMerge?: boolean;
   errorMessages?: boolean;
   fullErrors?: boolean;
   subSchemas?: Array<any>;
@@ -41,7 +42,9 @@ export class Cabidela {
       for (const subSchema of this.options.subSchemas as []) {
         this.addSchema(subSchema, false);
       }
-      traverseSchema(this.definitions, this.schema);
+    }
+    if (this.options.useMerge || (this.options.subSchemas as []).length > 0) {
+      traverseSchema(this.options, this.definitions, this.schema);
     }
   }
 
@@ -62,7 +65,7 @@ export class Cabidela {
     } else {
       throw new Error("subSchemas need $id https://json-schema.org/understanding-json-schema/structuring#id");
     }
-    if (combine == true) traverseSchema(this.definitions, this.schema);
+    if (combine == true) traverseSchema(this.options, this.definitions, this.schema);
   }
 
   getSchema() {

tests/09-merge.test.ts

@@ -0,0 +1,76 @@
+import { expect, describe, test } from "vitest";
+import { FakeCabidela } from "./lib/fake-cabidela";
+
+describe("$merge", () => {
+  test.skipIf(process.env.AJV)("two objects", () => {
+    let schema = {
+      $merge: {
+        source: {
+          type: "object",
+          properties: { p: { type: "string" } },
+          additionalProperties: false,
+        },
+        with: {
+          properties: { q: { type: "number" } },
+        },
+      },
+    };
+    const cabidela = new FakeCabidela(schema, { useMerge: true });
+    schema = cabidela.getSchema();
+    expect(schema).toStrictEqual({
+      type: "object",
+      properties: { p: { type: "string" }, q: { type: "number" } },
+      additionalProperties: false,
+    });
+  });
+
+  test.skipIf(process.env.AJV)("two objects, with arrays", () => {
+    let schema = {
+      $merge: {
+        source: {
+          type: "object",
+          properties: { p: [1, 2] },
+        },
+        with: {
+          properties: { p: [3, 4] },
+        },
+      },
+    };
+    const cabidela = new FakeCabidela(schema, { useMerge: true });
+    schema = cabidela.getSchema();
+    expect(schema).toStrictEqual({
+      type: "object",
+      properties: { p: [1, 2, 3, 4] },
+    });
+  });
+
+  test.skipIf(process.env.AJV)("two objects, with $defs and $ref", () => {
+    let schema = {
+      $merge: {
+        source: {
+          type: "object",
+          properties: { p: { type: "string" } },
+          additionalProperties: false,
+        },
+        with: {
+          properties: {
+            q: {
+              type: "string",
+              maxLength: { $ref: "$defs#/max_tokens" },
+            },
+          },
+        },
+      },
+      $defs: {
+        max_tokens: 250,
+      },
+    };
+    const cabidela = new FakeCabidela(schema, { useMerge: true });
+    schema = cabidela.getSchema();
+    expect(schema).toStrictEqual({
+      type: "object",
+      properties: { p: { type: "string" }, q: { type: "string", maxLength: 250 } },
+      additionalProperties: false,
+    });
+  });
+});

tests/lib/fake-cabidela.ts

@@ -23,6 +23,9 @@ export class FakeCabidela {
         strict: false,
         useDefaults: this.options.applyDefaults ? true : false,
       });
+      if (this.options.useMerge) {
+        require("ajv-merge-patch")(this.ajv);
+      }
       if (this.options.subSchemas) {
         this.options.subSchemas.forEach((subSchema: any) => {
           this.ajv.addSchema(subSchema);
@@ -67,7 +70,7 @@ export class FakeCabidela {
       const valid = this.validator(payload);
       if (!valid) {
         const description = this.validator.errors
-          .map((e:any) => {
+          .map((e: any) => {
             const instancePath = e.instancePath.split("/").join("");
             return instancePath === "" ? e.message : `'${instancePath}' ${e.message}`;
           })