@pdtf/schemas 3.2.1-14 → 3.2.1-16

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-14",
+  "version": "3.2.1-16",
   "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/schemas/v3/combined.json

@@ -1377,7 +1377,9 @@
                       "Trunk road/motorway",
                       "Airport",
                       "Helipad",
-                      "Other"
+                      "Other",
+                      "Tramway",
+                      "Underground/Subway"
                     ]
                   },
                   "latitude": {
@@ -3954,6 +3956,7 @@
                         }
                       }
                     },
+                    "ntsRequired": ["managedFreeholdOrCommonholdInformation"],
                     "fme1Required": ["managedFreeholdOrCommonholdInformation"],
                     "baspi4Required": [
                       "managedFreeholdOrCommonholdInformation"
@@ -8954,6 +8957,7 @@
                         }
                       }
                     },
+                    "ntsRequired": ["leaseholdInformation"],
                     "lpe1Required": ["leaseholdInformation"],
                     "baspi4Required": ["leaseholdInformation"],
                     "baspi5Required": ["leaseholdInformation"],

package/src/schemas/v3/overlays/nts.json

@@ -275,7 +275,10 @@
                           }
                         }
                       }
-                    }
+                    },
+                    "required": [
+                      "managedFreeholdOrCommonholdInformation"
+                    ]
                   },
                   {
                     "properties": {
@@ -524,7 +527,10 @@
                           }
                         }
                       }
-                    }
+                    },
+                    "required": [
+                      "leaseholdInformation"
+                    ]
                   },
                   {
                     "properties": {

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

@@ -1095,7 +1095,9 @@
                       "Trunk road/motorway",
                       "Airport",
                       "Helipad",
-                      "Other"
+                      "Other",
+                      "Tramway",
+                      "Underground/Subway"
                     ]
                   },
                   "latitude": {

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");
@@ -90,6 +91,18 @@ test("sample with missing dependent required fields is invalid", () => {
   expect(isValid).toBe(false);
 });
 
+test("sample with missing dependent required fields with NTS overlay is invalid", () => {
+  // Previously a required field was missing from the NTS overlay
+  const clonedExampleTransaction = JSON.parse(
+    JSON.stringify(exampleTransaction)
+  );
+  clonedExampleTransaction.propertyPack.ownership.ownershipsToBeTransferred[0].leaseholdInformation =
+    undefined;
+  const validator = getValidator(schemaId, ["nts2023"]);
+  const isValid = validator(clonedExampleTransaction);
+  expect(isValid).toBe(false);
+});
+
 test("correctly gets a top level subschema", () => {
   const subschema = getSubschema("/propertyPack");
   expect(subschema.title).toBe("Property Pack");
@@ -403,3 +416,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");
+});