@pdtf/schemas 3.2.1-9 → 3.3.0

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-9",
+  "version": "3.3.0",
   "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

@@ -976,5 +976,59 @@
         "contentTypes": ["Environmental Risks"]
       }
     ]
-  }
+  },
+  "contracts": [
+    {
+      "contract": {
+        "template": {
+          "name": "Example Agency Agreement",
+          "url": "https://example.com/example-agency-agreement",
+          "externalIds": {
+            "Moverly": "file123"
+          },
+          "requiredSignatories": [
+            {
+              "role": "Seller",
+              "requiresAll": true
+            }
+          ]
+        },
+        "terms": {
+          "propertyAddress": "123 Maple Street, London, SW1A 1AA",
+          "sellersNames": "Peter and Clarissa Hetherington-Smythe",
+          "sellersContactAddress": "47 Park Road, Harpenden, AL3 5AF",
+          "sellersTelephoneNumber": "07700 900123",
+          "sellersEmail": "peter.hetherington-smyth@email.com",
+          "typeOfAgency": "Sole Agency",
+          "feeAsPercent": "1.5%",
+          "fixedFeeExVat": "£2,500",
+          "estimatedFeeIncludingVat": "£3,000",
+          "includeAdditionalChargeEpc": true,
+          "additionalChargeForEpcExVat": "75",
+          "includeAdditionalChargeForEpcAndFloorplan": true,
+          "additionalChargeForEpcAndFloorplanExVat": "150",
+          "includeAdditionalChargeForEpcFloorplanAndPhotos": true,
+          "additionalChargeForEpcFloorplanAndPhotosExVat": "150",
+          "includeAdditionalChargeForPremiumPhotos ": true,
+          "additionalChargeForPremiumPhotosExVat": "150",
+          "includeAdditionalChargeForBrochure": true,
+          "additionalChargeForBrochureExVat": "150",
+          "includeAdditionalChargeForBespokeAdvertising": true,
+          "additionalChargeForBespokeAdvertisingExVat": "150",
+          "initialMarketingPrice": "£450,000"
+        }
+      },
+      "signatures": [
+        {
+          "name": "Peter Ronald Hetherington-Smythe",
+          "signedOn": "2024-11-29T16:15:02.735Z",
+          "externalIds": {
+            "Moverly": "123434"
+          },
+          "role": "Seller",
+          "contractHash": "IYnBjUI8TauXFop6WCvnPA=="
+        }
+      ]
+    }
+  ]
 }

package/src/schemas/v3/combined.json

@@ -185,6 +185,9 @@
           },
           "externalIds": {
             "type": "object"
+          },
+          "isRemoved": {
+            "type": "boolean"
           }
         },
         "discriminator": {
@@ -235,6 +238,7 @@
                       "Personal Representative for a Deceased Owner",
                       "Under Power of Attorney",
                       "Mortgagee in Possession",
+                      "Assistant",
                       "Other"
                     ]
                   }
@@ -271,6 +275,7 @@
                         "enum": [
                           "Personal Representative for a Deceased Owner",
                           "Under Power of Attorney",
+                          "Assistant",
                           "Other"
                         ]
                       },
@@ -1372,7 +1377,9 @@
                       "Trunk road/motorway",
                       "Airport",
                       "Helipad",
-                      "Other"
+                      "Other",
+                      "Tramway",
+                      "Underground/Subway"
                     ]
                   },
                   "latitude": {
@@ -3949,6 +3956,7 @@
                         }
                       }
                     },
+                    "ntsRequired": ["managedFreeholdOrCommonholdInformation"],
                     "fme1Required": ["managedFreeholdOrCommonholdInformation"],
                     "baspi4Required": [
                       "managedFreeholdOrCommonholdInformation"
@@ -8949,6 +8957,7 @@
                         }
                       }
                     },
+                    "ntsRequired": ["leaseholdInformation"],
                     "lpe1Required": ["leaseholdInformation"],
                     "baspi4Required": ["leaseholdInformation"],
                     "baspi5Required": ["leaseholdInformation"],
@@ -26332,6 +26341,32 @@
               "sr24Ref": "1.2",
               "title": "I/we consent to the sharing of the information contained in the Sale Ready pack with the my/our legal representative and the buyer(s) and their legal representatives",
               "type": "boolean"
+            },
+            "sellerSignatures": {
+              "sr24Ref": "1.3",
+              "title": "I confirm that all information provided is accurate to the best of my knowledge and if I become aware of any change to/changes which alter the information supplied/provided prior to exchange of contracts for the sale of the property, I will immediately notify the person marketing the property as well as my property lawyer.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["name", "signedOn"],
+                "properties": {
+                  "name": {
+                    "sr24Ref": "1.3.1",
+                    "title": "Name of signatory",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "signedOn": {
+                    "sr24Ref": "1.3.2",
+                    "title": "Date and time of signature in ISO 8601 format",
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "externalIds": {
+                    "type": "object"
+                  }
+                }
+              }
             }
           }
         },
@@ -28903,9 +28938,9 @@
                             }
                           ]
                         },
-                        "floodAndCostalErosionRiskManagement": {
+                        "floodAndCoastalErosionRiskManagement": {
                           "con29RRef": "3.7(g)",
-                          "title": "flood and costal erosion risk management",
+                          "title": "flood and coastal erosion risk management",
                           "type": "object",
                           "properties": {
                             "yesNo": {
@@ -39285,6 +39320,95 @@
           }
         }
       }
+    },
+    "contracts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "contract": {
+            "type": "object",
+            "required": ["template", "terms"],
+            "properties": {
+              "template": {
+                "type": "object",
+                "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" }
+                      }
+                    }
+                  }
+                }
+              },
+              "terms": {
+                "type": "object"
+              }
+            }
+          },
+          "signatures": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "signedOn", "role", "contractHash"],
+              "properties": {
+                "name": { "type": "string" },
+                "signedOn": { "type": "string", "format": "date-time" },
+                "externalIds": {
+                  "type": "object"
+                }
+              },
+              "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"
+                ]
+              },
+              "contractHash": {
+                "title": "An MD5 hash of the stable-stringified contract object being signed",
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -67,6 +67,7 @@
                         "enum": [
                           "Personal Representative for a Deceased Owner",
                           "Under Power of Attorney",
+                          "Assistant",
                           "Other"
                         ]
                       },

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

@@ -67,6 +67,7 @@
                         "enum": [
                           "Personal Representative for a Deceased Owner",
                           "Under Power of Attorney",
+                          "Assistant",
                           "Other"
                         ]
                       },

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

@@ -1481,7 +1481,7 @@
                             "yesNo"
                           ]
                         },
-                        "floodAndCostalErosionRiskManagement": {
+                        "floodAndCoastalErosionRiskManagement": {
                           "con29RRef": "3.7(g)",
                           "discriminator": {
                             "propertyName": "yesNo"

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/overlays/piq.json

@@ -57,6 +57,7 @@
                         "enum": [
                           "Personal Representative for a Deceased Owner",
                           "Under Power of Attorney",
+                          "Assistant",
                           "Other"
                         ]
                       }

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

@@ -33,6 +33,7 @@
                         "enum": [
                           "Personal Representative for a Deceased Owner",
                           "Under Power of Attorney",
+                          "Assistant",
                           "Other"
                         ]
                       },

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

@@ -16,6 +16,19 @@
             },
             "authorisationToShare": {
               "sr24Ref": "1.2"
+            },
+            "sellerSignatures": {
+              "sr24Ref": "1.3",
+              "items": {
+                "properties": {
+                  "name": {
+                    "sr24Ref": "1.3.1"
+                  },
+                  "signedOn": {
+                    "sr24Ref": "1.3.2"
+                  }
+                }
+              }
             }
           }
         }

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

@@ -182,6 +182,9 @@
           },
           "externalIds": {
             "type": "object"
+          },
+          "isRemoved": {
+            "type": "boolean"
           }
         },
         "oneOf": [
@@ -223,6 +226,7 @@
                       "Personal Representative for a Deceased Owner",
                       "Under Power of Attorney",
                       "Mortgagee in Possession",
+                      "Assistant",
                       "Other"
                     ]
                   }
@@ -257,6 +261,7 @@
                         "enum": [
                           "Personal Representative for a Deceased Owner",
                           "Under Power of Attorney",
+                          "Assistant",
                           "Other"
                         ]
                       },
@@ -1090,7 +1095,9 @@
                       "Trunk road/motorway",
                       "Airport",
                       "Helipad",
-                      "Other"
+                      "Other",
+                      "Tramway",
+                      "Underground/Subway"
                     ]
                   },
                   "latitude": {
@@ -21689,6 +21696,32 @@
             "authorisationToShare": {
               "title": "I/we consent to the sharing of the information contained in the Sale Ready pack with the my/our legal representative and the buyer(s) and their legal representatives",
               "type": "boolean"
+            },
+            "sellerSignatures": {
+              "title": "I confirm that all information provided is accurate to the best of my knowledge and if I become aware of any change to/changes which alter the information supplied/provided prior to exchange of contracts for the sale of the property, I will immediately notify the person marketing the property as well as my property lawyer.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "signedOn"
+                ],
+                "properties": {
+                  "name": {
+                    "title": "Name of signatory",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "signedOn": {
+                    "title": "Date and time of signature in ISO 8601 format",
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "externalIds": {
+                    "type": "object"
+                  }
+                }
+              }
             }
           }
         },
@@ -24233,8 +24266,8 @@
                             }
                           ]
                         },
-                        "floodAndCostalErosionRiskManagement": {
-                          "title": "flood and costal erosion risk management",
+                        "floodAndCoastalErosionRiskManagement": {
+                          "title": "flood and coastal erosion risk management",
                           "type": "object",
                           "properties": {
                             "yesNo": {
@@ -34089,6 +34122,119 @@
           }
         }
       }
+    },
+    "contracts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "contract": {
+            "type": "object",
+            "required": [
+              "template",
+              "terms"
+            ],
+            "properties": {
+              "template": {
+                "type": "object",
+                "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"
+                        }
+                      }
+                    }
+                  }
+                }
+              },
+              "terms": {
+                "type": "object"
+              }
+            }
+          },
+          "signatures": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "name",
+                "signedOn",
+                "role",
+                "contractHash"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "signedOn": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "externalIds": {
+                  "type": "object"
+                }
+              },
+              "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"
+                ]
+              },
+              "contractHash": {
+                "title": "An MD5 hash of the stable-stringified contract object being signed",
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

package/src/schemas/v3/skeleton.json

@@ -30,6 +30,7 @@
     "organisationReference": {},
     "role": {},
     "externalIds": {},
+    "isRemoved": {},
     "sellersCapacity": {
       "capacity": {},
       "sellersCapacityDetails": {},
@@ -2816,7 +2817,12 @@
     },
     "saleReadyDeclarations": {
       "authorisedToActOnBehalfOfAllSellers": {},
-      "authorisationToShare": {}
+      "authorisationToShare": {},
+      "sellerSignatures": {
+        "name": {},
+        "signedOn": {},
+        "externalIds": {}
+      }
     },
     "localSearches": {
       "localLandCharges": {
@@ -3181,7 +3187,7 @@
               "yesNo": {},
               "details": {}
             },
-            "floodAndCostalErosionRiskManagement": {
+            "floodAndCoastalErosionRiskManagement": {
               "yesNo": {},
               "details": {}
             }
@@ -4089,5 +4095,24 @@
         "pricingMethodology": {}
       }
     }
+  },
+  "contracts": {
+    "contract": {
+      "template": {
+        "name": {},
+        "url": {},
+        "externalIds": {},
+        "requiredSignatories": {
+          "role": {},
+          "requiresAll": {}
+        }
+      },
+      "terms": {}
+    },
+    "signatures": {
+      "name": {},
+      "signedOn": {},
+      "externalIds": {}
+    }
   }
 }

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");
@@ -396,3 +409,234 @@ test("correctly gets titles across schemas, arrays and non-existient title prope
     )
   ).toBe("Please provide their full names and ages.");
 });
+test("validates a valid contract", () => {
+  const path = "/contracts";
+  const data = jp.get(exampleTransaction, path);
+  const validator = getSubschemaValidator(path, exampleTransaction.$schema);
+  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");
+});