@pdtf/schemas 3.2.1-13 → 3.2.1-15

package/index.js

@@ -61,14 +61,49 @@ const transactionSchemas = {
 };
 
 const combineMerge = (target, source, options) => {
+  // Special handling for 'required' arrays - combine them uniquely
+  if (target.some((item) => typeof item === "string")) {
+    return [...new Set([...target, ...source])];
+  }
+
+  // For other arrays, concatenate while preserving uniqueness for primitive values
+  if (!options.isMergeableObject(target[0])) {
+    return [...new Set([...target, ...source])];
+  }
+
+  // Special handling for oneOf arrays - merge matching schemas based on discriminator
+  if (target[0]?.properties && source[0]?.properties) {
+    // Find a common discriminator property (a property with an enum)
+    const findDiscriminator = (schema) => {
+      const props = schema.properties;
+      return Object.keys(props).find((key) => Array.isArray(props[key]?.enum));
+    };
+
+    const discriminator = findDiscriminator(target[0]);
+    if (discriminator) {
+      return target.map((targetSchema) => {
+        const targetEnum = targetSchema.properties?.[discriminator]?.enum || [];
+        const matchingSourceSchema = source.find((sourceSchema) => {
+          const sourceEnum =
+            sourceSchema.properties?.[discriminator]?.enum || [];
+          // Check if there's any overlap between the enum values
+          return sourceEnum.some((value) => targetEnum.includes(value));
+        });
+        if (matchingSourceSchema) {
+          return merge(targetSchema, matchingSourceSchema, options);
+        }
+        return targetSchema;
+      });
+    }
+  }
+
+  // For arrays of objects, merge by index and append remaining items
   const destination = target.slice();
   source.forEach((item, index) => {
     if (typeof destination[index] === "undefined") {
       destination[index] = options.cloneUnlessOtherwiseSpecified(item, options);
     } else if (options.isMergeableObject(item)) {
       destination[index] = merge(target[index], item, options);
-    } else if (target.indexOf(item) === -1) {
-      destination.push(item);
     }
   });
   return destination;
@@ -84,7 +119,12 @@ const getTransactionSchema = (
   if (!overlays || overlays.length < 1) return sourceSchema;
   let mergedSchema = sourceSchema;
   overlays.forEach((overlay) => {
-    const overlaySchema = overlaysMap[schemaId][overlay] || {};
+    // Handle both string keys and direct overlay objects
+    const overlaySchema =
+      typeof overlay === "string"
+        ? overlaysMap[schemaId][overlay] || {}
+        : overlay;
+
     mergedSchema = merge(mergedSchema, overlaySchema, {
       customMerge: (key) => {
         if (key === "enum") {
@@ -97,6 +137,23 @@ const getTransactionSchema = (
   return mergedSchema;
 };
 
+// Add helper function to generate cache key
+const generateOverlayKey = (overlays) => {
+  if (!overlays) return "";
+  return overlays
+    .map((overlay) => {
+      if (typeof overlay === "string") return overlay;
+      // Generate a simple hash of the object for caching
+      return JSON.stringify(overlay)
+        .split("")
+        .reduce((hash, char) => {
+          return ((hash << 5) - hash + char.charCodeAt(0)) | 0;
+        }, 0)
+        .toString(36);
+    })
+    .join(".");
+};
+
 const getValidator = (schemaId, overlays) => {
   return getSubschemaValidator("", schemaId, overlays);
 };
@@ -135,7 +192,7 @@ const isPathValid = (path, schemaId, overlays) => {
 
 const getSubschemaValidator = (path, schemaId, overlays) => {
   const subSchema = getSubschema(path, schemaId, overlays);
-  const overlayKey = (overlays || []).join(".");
+  const overlayKey = generateOverlayKey(overlays);
   // see if we can retrieve the schema by path, schemaId and overlays
   const cacheKey = `${path}-${schemaId}-${overlayKey}`;
   let validator = ajv.getSchema(cacheKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdtf/schemas",
-  "version": "3.2.1-13",
+  "version": "3.2.1-15",
   "description": "Property Data Trust Framework Schemas and Utilities",
   "main": "index.js",
   "directories": {

package/src/examples/v3/exampleCustomOverlay.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://trust.propdata.org.uk/schemas/v3/overlays/custom.json",
+  "properties": {
+    "propertyPack": {
+      "customRef": "JKW",
+      "type": "object",
+      "required": ["specialistIssues"],
+      "properties": {
+        "specialistIssues": {
+          "customRef": "JKW.7",
+          "required": ["japaneseKnotweed"],
+          "properties": {
+            "japaneseKnotweed": {
+              "customRef": "JKW.7.8",
+              "discriminator": {
+                "propertyName": "yesNo"
+              },
+              "oneOf": [
+                {
+                  "properties": {
+                    "yesNo": {
+                      "enum": ["No", "Not known"]
+                    }
+                  }
+                },
+                {
+                  "properties": {
+                    "yesNo": {
+                      "enum": ["Yes"]
+                    },
+                    "managementPlanInPlace": {
+                      "customRef": "JKW.7.8.2"
+                    },
+                    "attachments": {
+                      "customRef": "JKW.7.8.3"
+                    }
+                  },
+                  "required": ["managementPlanInPlace", "attachments"]
+                }
+              ],
+              "required": ["yesNo"],
+              "title": "Is the property affected by Japanese knotweed?",
+              "properties": {
+                "yesNo": {
+                  "customRef": "JKW.7.8.1"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/examples/v3/exampleCustomOverlay2.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://trust.propdata.org.uk/schemas/v3/overlays/ta7.json",
+  "properties": {
+    "propertyPack": {
+      "macRef": "MAC",
+      "required": ["ownership"],
+      "properties": {
+        "ownership": {
+          "macRef": "MAC.1",
+          "required": ["ownershipsToBeTransferred"],
+          "properties": {
+            "ownershipsToBeTransferred": {
+              "macRef": "MAC.1",
+              "items": {
+                "discriminator": {
+                  "propertyName": "ownershipType"
+                },
+                "oneOf": [
+                  {
+                    "properties": {
+                      "ownershipType": {
+                        "enum": ["Leasehold"]
+                      },
+                      "leaseholdInformation": {
+                        "required": ["contactDetails"],
+                        "properties": {
+                          "contactDetails": {
+                            "macRef": "MAC.4.1",
+                            "required": ["contacts"],
+                            "properties": {
+                              "contacts": {
+                                "macRef": "MAC.4.1",
+                                "required": ["managingAgent"],
+                                "properties": {
+                                  "managingAgent": {
+                                    "macRef": "MAC.4.1c",
+                                    "required": ["contact"],
+                                    "properties": {
+                                      "contact": {
+                                        "macRef": "MAC.4.1c",
+                                        "required": ["nameOrOrganisation"],
+                                        "properties": {
+                                          "nameOrOrganisation": {
+                                            "macRef": "MAC.4.1c.1"
+                                          },
+                                          "address": {
+                                            "macRef": "MAC.4.1c.0",
+                                            "properties": {
+                                              "line1": {
+                                                "macRef": "MAC.4.1c.2"
+                                              },
+                                              "line2": {
+                                                "macRef": "MAC.4.1c.3"
+                                              },
+                                              "line3": {
+                                                "macRef": "MAC.4.1c.4"
+                                              },
+                                              "town": {
+                                                "macRef": "MAC.4.1c.5"
+                                              },
+                                              "postcode": {
+                                                "macRef": "MAC.4.1c.6"
+                                              }
+                                            }
+                                          },
+                                          "telephone": {
+                                            "macRef": "MAC.4.1c.7"
+                                          },
+                                          "emailAddress": {
+                                            "macRef": "MAC.4.1c.8"
+                                          }
+                                        }
+                                      }
+                                    }
+                                  }
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/examples/v3/exampleTransaction.json

@@ -985,7 +985,13 @@
           "url": "https://example.com/example-agency-agreement",
           "externalIds": {
             "Moverly": "file123"
-          }
+          },
+          "requiredSignatories": [
+            {
+              "role": "Seller",
+              "requiresAll": true
+            }
+          ]
         },
         "terms": {
           "propertyAddress": "123 Maple Street, London, SW1A 1AA",

package/src/schemas/v3/combined.json

@@ -39328,12 +39328,38 @@
             "properties": {
               "template": {
                 "type": "object",
-                "required": ["name", "url"],
+                "required": ["name", "url", "requiredSignatories"],
                 "properties": {
                   "name": { "type": "string" },
                   "url": { "type": "string", "format": "uri" },
                   "externalIds": {
                     "type": "object"
+                  },
+                  "requiredSignatories": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "role": {
+                          "type": "string",
+                          "enum": [
+                            "Seller",
+                            "Seller's Conveyancer",
+                            "Prospective Buyer",
+                            "Buyer",
+                            "Buyer's Conveyancer",
+                            "Estate Agent",
+                            "Buyer's Agent",
+                            "Surveyor",
+                            "Mortgage Broker",
+                            "Lender",
+                            "Landlord",
+                            "Tenant"
+                          ]
+                        },
+                        "requiresAll": { "type": "boolean" }
+                      }
+                    }
                   }
                 }
               },

package/src/schemas/v3/pdtf-transaction.json

@@ -34137,7 +34137,8 @@
                 "type": "object",
                 "required": [
                   "name",
-                  "url"
+                  "url",
+                  "requiredSignatories"
                 ],
                 "properties": {
                   "name": {
@@ -34149,6 +34150,34 @@
                   },
                   "externalIds": {
                     "type": "object"
+                  },
+                  "requiredSignatories": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "role": {
+                          "type": "string",
+                          "enum": [
+                            "Seller",
+                            "Seller's Conveyancer",
+                            "Prospective Buyer",
+                            "Buyer",
+                            "Buyer's Conveyancer",
+                            "Estate Agent",
+                            "Buyer's Agent",
+                            "Surveyor",
+                            "Mortgage Broker",
+                            "Lender",
+                            "Landlord",
+                            "Tenant"
+                          ]
+                        },
+                        "requiresAll": {
+                          "type": "boolean"
+                        }
+                      }
+                    }
                   }
                 }
               },

package/src/schemas/v3/skeleton.json

@@ -4101,7 +4101,11 @@
       "template": {
         "name": {},
         "url": {},
-        "externalIds": {}
+        "externalIds": {},
+        "requiredSignatories": {
+          "role": {},
+          "requiresAll": {}
+        }
       },
       "terms": {}
     },

package/src/tests/v3/transactionSchema.test.js

@@ -8,6 +8,7 @@ const {
   getValidator,
   getSubschemaValidator,
   getTitleAtPath,
+  overlaysMap,
 } = require("../../../index.js");
 
 const exampleTransaction = require("../../examples/v3/exampleTransaction.json");
@@ -403,3 +404,227 @@ test("validates a valid contract", () => {
   const isValid = validator(data);
   expect(isValid).toBe(true);
 });
+
+test("overlay as key and as object produce identical results", () => {
+  // Get the NTS overlay object directly from the overlays map
+  const ntsOverlayObject = { ...overlaysMap[schemaId]["nts2023"] };
+  // Remove the $id to prevent schema registration conflicts
+  ntsOverlayObject.$id =
+    "https://trust.propdata.org.uk/schemas/v3/overlays/nts2024.json";
+
+  // Get schema using the key
+  const schemaWithKey = getTransactionSchema(schemaId, ["nts2023"]);
+
+  // Get schema using the object
+  const schemaWithObject = getTransactionSchema(schemaId, [ntsOverlayObject]);
+
+  // Create copies without $id for comparison
+  const schemaWithKeyNoId = { ...schemaWithKey };
+  const schemaWithObjectNoId = { ...schemaWithObject };
+  delete schemaWithKeyNoId.$id;
+  delete schemaWithObjectNoId.$id;
+
+  // Deep compare the results (excluding $id)
+  expect(schemaWithObjectNoId).toEqual(schemaWithKeyNoId);
+
+  // Test that validation produces the same errors
+  const validatorWithKey = getValidator(schemaId, ["nts2023"]);
+  const validatorWithObject = getValidator(schemaId, [ntsOverlayObject]);
+
+  validatorWithKey(exampleTransaction);
+  validatorWithObject(exampleTransaction);
+
+  // Compare validation errors
+  expect(validatorWithObject.errors).toEqual(validatorWithKey.errors);
+});
+
+test("correctly merges custom Japanese Knotweed overlay with base schema", () => {
+  // Load the custom overlay
+  const customOverlay = require("../../examples/v3/exampleCustomOverlay.json");
+
+  // Get base schema and schema with overlay
+  const baseSchema = getTransactionSchema(schemaId);
+  const schemaWithOverlay = getTransactionSchema(schemaId, [customOverlay]);
+
+  // Verify that other properties in propertyPack are preserved
+  expect(
+    Object.keys(schemaWithOverlay.properties.propertyPack.properties)
+  ).toEqual(Object.keys(baseSchema.properties.propertyPack.properties));
+
+  // Verify that other properties in specialistIssues are preserved
+  const baseSpecialistIssues =
+    baseSchema.properties.propertyPack.properties.specialistIssues;
+  const overlaidSpecialistIssues =
+    schemaWithOverlay.properties.propertyPack.properties.specialistIssues;
+  expect(Object.keys(overlaidSpecialistIssues.properties)).toEqual(
+    Object.keys(baseSpecialistIssues.properties)
+  );
+
+  // Verify that Japanese Knotweed section is updated
+  const japaneseKnotweed = overlaidSpecialistIssues.properties.japaneseKnotweed;
+  expect(japaneseKnotweed.title).toBe(
+    "Is the property affected by Japanese knotweed?"
+  );
+  expect(japaneseKnotweed.required).toEqual(["yesNo"]);
+
+  // Verify the oneOf conditions are updated
+  expect(japaneseKnotweed.oneOf).toHaveLength(2);
+  expect(japaneseKnotweed.oneOf[0].properties.yesNo.enum).toEqual([
+    "No",
+    "Not known",
+  ]);
+  expect(japaneseKnotweed.oneOf[1].properties.yesNo.enum).toEqual(["Yes"]);
+  expect(japaneseKnotweed.oneOf[1].required).toEqual([
+    "managementPlanInPlace",
+    "attachments",
+  ]);
+});
+
+test("correctly merges multiple overlays using both key and object references", () => {
+  // Load the custom overlay
+  const customOverlay = require("../../examples/v3/exampleCustomOverlay.json");
+
+  // Get schema with both overlays
+  const schemaWithOverlays = getTransactionSchema(schemaId, [
+    "nts2023",
+    customOverlay,
+  ]);
+
+  // Get individual overlay schemas for comparison
+  const ntsSchema = getTransactionSchema(schemaId, ["nts2023"]);
+  const customSchema = getTransactionSchema(schemaId, [customOverlay]);
+
+  // Verify propertyPack structure is preserved
+  const propertyPack = schemaWithOverlays.properties.propertyPack;
+  expect(Object.keys(propertyPack.properties)).toEqual(
+    expect.arrayContaining(
+      Object.keys(ntsSchema.properties.propertyPack.properties)
+    )
+  );
+
+  // Verify Japanese Knotweed changes from custom overlay are present
+  const japaneseKnotweed =
+    propertyPack.properties.specialistIssues.properties.japaneseKnotweed;
+  expect(japaneseKnotweed.title).toBe(
+    "Is the property affected by Japanese knotweed?"
+  );
+  expect(japaneseKnotweed.oneOf[1].required).toEqual([
+    "managementPlanInPlace",
+    "attachments",
+  ]);
+
+  // Verify customRef properties are correctly merged
+  expect(propertyPack.customRef).toBe("JKW");
+  expect(propertyPack.properties.specialistIssues.customRef).toBe("JKW.7");
+  expect(japaneseKnotweed.customRef).toBe("JKW.7.8");
+  expect(
+    japaneseKnotweed.oneOf[1].properties.managementPlanInPlace.customRef
+  ).toBe("JKW.7.8.2");
+  expect(japaneseKnotweed.oneOf[1].properties.attachments.customRef).toBe(
+    "JKW.7.8.3"
+  );
+  expect(japaneseKnotweed.properties.yesNo.customRef).toBe("JKW.7.8.1");
+
+  // Verify NTS specific changes are present (e.g., simplified enums)
+  const mainsElectricity =
+    propertyPack.properties.electricity.properties.mainsElectricity;
+  expect(mainsElectricity.properties.yesNo.enum).toEqual(["Yes", "No"]);
+
+  // Verify required fields from both overlays are merged
+  expect(propertyPack.required).toEqual(
+    expect.arrayContaining([
+      ...ntsSchema.properties.propertyPack.required,
+      ...customSchema.properties.propertyPack.required,
+    ])
+  );
+});
+
+test("correctly merges NTS and both custom overlays with proper required fields", () => {
+  // Load both custom overlays
+  const japaneseKnoweedOverlay = require("../../examples/v3/exampleCustomOverlay.json");
+  const managingAgentOverlay = require("../../examples/v3/exampleCustomOverlay2.json");
+
+  // Get schema with all overlays
+  const schemaWithOverlays = getTransactionSchema(schemaId, [
+    "nts2023",
+    japaneseKnoweedOverlay,
+    managingAgentOverlay,
+  ]);
+
+  // Navigate to the leasehold section in the oneOf array
+  const leaseholdSchema =
+    schemaWithOverlays.properties.propertyPack.properties.ownership.properties.ownershipsToBeTransferred.items.oneOf.find(
+      (schema) => schema.properties.ownershipType.enum[0] === "Leasehold"
+    );
+
+  // Verify the leasehold information structure
+  const leaseholdInfo = leaseholdSchema.properties.leaseholdInformation;
+
+  // Check required fields - should include both NTS and custom overlay requirements
+  expect(leaseholdInfo.required).toContain("contactDetails");
+  expect(leaseholdInfo.required).toContain("leaseTerm"); // from NTS
+  expect(leaseholdInfo.required).toContain("groundRent"); // from NTS
+
+  // Verify managing agent contact structure and refs
+  const managingAgent =
+    leaseholdInfo.properties.contactDetails.properties.contacts.properties
+      .managingAgent;
+  expect(managingAgent.macRef).toBe("MAC.4.1c");
+
+  // Verify contact details structure
+  const contact = managingAgent.properties.contact;
+  expect(contact.properties.nameOrOrganisation.macRef).toBe("MAC.4.1c.1");
+  expect(contact.properties.address.macRef).toBe("MAC.4.1c.0");
+  expect(contact.properties.telephone.macRef).toBe("MAC.4.1c.7");
+  expect(contact.properties.emailAddress.macRef).toBe("MAC.4.1c.8");
+
+  // Verify Japanese Knotweed section is still present and correct
+  const japaneseKnotweed =
+    schemaWithOverlays.properties.propertyPack.properties.specialistIssues
+      .properties.japaneseKnotweed;
+  expect(japaneseKnotweed.customRef).toBe("JKW.7.8");
+
+  // Verify NTS changes are still present
+  const mainsElectricity =
+    schemaWithOverlays.properties.propertyPack.properties.electricity.properties
+      .mainsElectricity;
+  expect(mainsElectricity.properties.yesNo.enum).toEqual(["Yes", "No"]);
+});
+
+test("ta7 overlay as key and as object produce identical results at leasehold info level", () => {
+  // Get the TA7 overlay object directly from the overlays map
+  const ta7OverlayObject = { ...overlaysMap[schemaId]["ta7ed3"] };
+  // Remove the $id to prevent schema registration conflicts
+  ta7OverlayObject.$id =
+    "https://trust.propdata.org.uk/schemas/v3/overlays/ta7ed3-copy.json";
+
+  // Get schemas using both methods
+  const schemaWithKey = getTransactionSchema(schemaId, ["ta7ed3"]);
+  const schemaWithObject = getTransactionSchema(schemaId, [ta7OverlayObject]);
+
+  // Navigate to the leasehold information section in both schemas
+  const getLeaseholdInfo = (schema) => {
+    const ownershipsToBeTransferred =
+      schema.properties.propertyPack.properties.ownership.properties
+        .ownershipsToBeTransferred;
+    const leaseholdSchema = ownershipsToBeTransferred.items.oneOf.find(
+      (schema) => schema.properties.ownershipType.enum[0] === "Leasehold"
+    );
+    return leaseholdSchema.properties.leaseholdInformation;
+  };
+
+  const leaseholdInfoWithKey = getLeaseholdInfo(schemaWithKey);
+  const leaseholdInfoWithObject = getLeaseholdInfo(schemaWithObject);
+
+  // Deep compare the leasehold information sections
+  expect(leaseholdInfoWithObject).toEqual(leaseholdInfoWithKey);
+
+  // Verify specific TA7 requirements are present in both
+  expect(leaseholdInfoWithKey.required).toContain("contactDetails");
+  expect(leaseholdInfoWithObject.required).toContain("contactDetails");
+
+  // Verify TA7 refs are present and identical
+  const contactDetails = leaseholdInfoWithKey.properties.contactDetails;
+  expect(contactDetails.ta7Ref).toBe("4.1");
+  expect(leaseholdInfoWithObject.properties.contactDetails.ta7Ref).toBe("4.1");
+});