@pdtf/schemas 3.6.0-32 → 3.6.0-34

package/README.md

@@ -7,7 +7,7 @@ The Property Data Trust Framework (PDTF) Schemas provide standardized JSON Schem
 
 ## Project Goals & Status
 
-**Current Version:** 3.5.0 (3.5.1-1 available as a pre-release on branch/package-tag `next`)
+**Current Version:** 3.6.0-32 (pre-release on branch/package-tag `next`)
 
 This schema framework aims to support the [Home Buying and Selling Group](https://homebuyingandsellinggroup.co.uk) 'Property Pack' initiative, encompassing all requirements starting with the Buyers and Sellers Property Information set ([BASPI v4.0](https://homebuyingandsellinggroup.co.uk/baspi/)).
 
@@ -62,7 +62,7 @@ if (!isValid) {
 
 - **🏗️ Modular Schema System** - Base schemas with flexible overlay composition
 - **📋 Multiple Form Support** - BASPI, NTS, Law Society TA forms, and more
-- **🧩 Extension Overlays** - Granular NTS2 features as individual modules
+- **🧩 Extension Overlays** - Granular NTS2 and SEF25 features as individual modules
 - **✅ JSON Schema Validation** - Full JSON Schema Draft 07 support with AJV
 - **🔗 Verified Claims** - Support for verified data provenance tracking
 - **📚 Comprehensive Documentation** - Detailed usage guides and examples
@@ -82,7 +82,7 @@ if (!isValid) {
 │   │   │   │   └── extensions/        # Modular NTS2 extensions
 │   │   │   │       ├── jk.json        # Japanese Knotweed
 │   │   │   │       ├── tf.json        # Transfer Fees
-│   │   │   │       └── ...            # 16 total extensions
+│   │   │   │       └── ...            # NTS2 + SEF25 extensions
 │   │   │   └── combined.json          # Master schema for generation
 │   │   ├── v2/                        # Legacy schema version
 │   │   ├── verifiedClaims/            # Verified claims schemas
@@ -163,31 +163,56 @@ const errors = validateVerifiedClaims(verifiedClaims, schemaId, ["nts2023"]);
 
 #### Extension Overlays
 
-Modular NTS2 features for selective adoption:
+Modular features for selective adoption. Extensions are merged on top of an NTS base overlay.
 
 ```javascript
-// Individual extensions
-const schema = getTransactionSchema(schemaId, ["nts2023", "jk", "tf"]);
-
-// Multiple specialist issues
-const schema = getTransactionSchema(schemaId, [
-  "nts2023",
-  "as",
-  "dr",
-  "jk",
-  "sb",
-]);
+// NTS2 extensions
+const schema = getTransactionSchema(schemaId, ["nts2023", "jk", "tf", "ma"]);
+
+// SEF25 extensions (Seller Enquiry Form)
+const sef25 = ["sc", "pc", "ph", "dk", "rw", "sd", "lc", "wg", "ic", "nd", "mi", "tr"];
+const schema = getTransactionSchema(schemaId, ["nts2023", ...sef25]);
 ```
 
-| Extension         | Code | Description                      |
-| ----------------- | ---- | -------------------------------- |
-| Japanese Knotweed | `jk` | Knotweed presence and management |
-| Transfer Fees     | `tf` | Additional leasehold fees        |
-| Managing Agent    | `ma` | Leasehold managing agent details |
-| Solar Panels      | `sl` | Solar panel ownership details    |
-| Asbestos          | `as` | Asbestos presence and management |
+**NTS2 Extensions:**
 
-[View all extensions →](src/schemas/v3/overlays/README.md#extension-overlays)
+| Extension | Code | Description |
+| --- | --- | --- |
+| Japanese Knotweed | `jk` | Knotweed presence and management |
+| Asbestos | `as` | Asbestos presence and management |
+| Dry Rot | `dr` | Dry rot treatment |
+| Subsidence | `sb` | Subsidence or structural fault |
+| Health & Safety | `hs` | Ongoing health or safety issues |
+| Outside Areas | `oa` | Outside areas details |
+| Main Construction | `mc` | Construction type if standard form |
+| Loft Access | `la` | Loft access and details |
+| Spray Foam | `sf` | Spray foam insulation |
+| Solar Panels | `sl` | Solar panel ownership details |
+| Heating Installed | `hi` | Central heating installation date |
+| Flood Defences | `fd` | Flood defence information |
+| Estate Rentcharges | `er` | Estate rentcharges for freehold |
+| Managing Agent | `ma` | Leasehold managing agent details |
+| Transfer Fees | `tf` | Additional leasehold fees |
+| Onward Chain | `oc` | Other property in chain |
+
+**SEF25 Extensions (Seller Enquiry Form):**
+
+| Extension | Code | Description |
+| --- | --- | --- |
+| Supply Costs | `sc` | Private water/sewerage costs |
+| Parking Permit Cost | `pc` | Parking permit frequency |
+| Property Hazards | `ph` | 4 hazard Yes/No questions |
+| Dropped Kerb | `dk` | Dropped kerb access to parking |
+| Private Right of Way | `rw` | Private right of way |
+| Storm/Fire/Flood Damage | `sd` | Storm, fire or flood damage |
+| Solar Lease Costs | `lc` | Solar panel lease costs |
+| Warranties & Guarantees | `wg` | 7 warranty categories upfront |
+| Insurance Claims | `ic` | Insurance claims upfront |
+| Neighbour Development | `nd` | Neighbour development |
+| Material Issue | `mi` | Other material issue upfront |
+| Title Restrictions | `tr` | Title restrictions for freehold |
+
+[View full SEF25 UI spec →](docs/sef25-extensions-ui-spec.md) | [View all extensions →](src/schemas/v3/overlays/README.md#extension-overlays)
 
 ## Usage Examples
 
@@ -204,7 +229,7 @@ const legalSchema = getTransactionSchema(schemaId, ["ta6ed4", "ta7ed3"]);
 const ntsSchema = getTransactionSchema(schemaId, ["nts2023"]);
 ```
 
-### Modular NTS2 Features
+### Modular Extension Features
 
 ```javascript
 // Selective NTS2 adoption
@@ -215,15 +240,9 @@ const partialNts2 = getTransactionSchema(schemaId, [
   "ma", // Managing Agent
 ]);
 
-// Full specialist issues
-const specialistIssues = getTransactionSchema(schemaId, [
-  "nts2023",
-  "as",
-  "dr",
-  "jk",
-  "sb",
-  "hs",
-]);
+// SEF25 Seller Enquiry Form extensions
+const sef25 = ["sc", "pc", "ph", "dk", "rw", "sd", "lc", "wg", "ic", "nd", "mi", "tr"];
+const sellerEnquiry = getTransactionSchema(schemaId, ["nts2023", ...sef25]);
 ```
 
 ### Data Validation

package/docs/sef25-extensions-ui-spec.md

@@ -4,72 +4,79 @@
 
 Extension overlays add follow-up questions to existing form sections. Each overlay is loaded by passing its key to `getTransactionSchema(schemaId, overlays)`.
 
+### Pre-existing overlays
+
+These were added before this PR and are already in production.
+
 | Overlay Key | Name | Section | Fields Added |
 |-------------|------|---------|-------------|
-| `sc` | Supply Costs | Water & Drainage | 2 cost fields (private water, private sewerage) |
+| `sc` | Supply Costs | Water & Drainage | Cost fields for private water and sewerage (restructured to hasCost Yes/No gate) |
 | `pc` | Parking Permit Cost | Parking | 1 frequency field |
 | `ph` | Property Hazards | Specialist Issues | 4 Yes/No + details fields |
+
+### New overlays (this PR)
+
+| Overlay Key | Name | Section | Fields Added |
+|-------------|------|---------|-------------|
 | `dk` | Dropped Kerb | Parking | 1 Yes/No field |
 | `rw` | Private Right of Way | Rights & Informal Arrangements | 1 Yes/No + details field |
 | `sd` | Storm/Fire/Flood Damage | Environmental Issues | 1 Yes/No + details field |
-| `lc` | Solar Lease Costs | Utilities (Solar Panels) | 1 cost field (amount + frequency) |
+| `lc` | Solar Lease Costs | Utilities (Solar Panels) | 1 cost field (hasCost + amount + frequency) |
 | `wg` | Warranties & Guarantees | Guarantees & Warranties | Marks 7 warranty categories as required |
-| `dc` | Disputes & Complaints | Disputes & Complaints | Marks hasDisputesAndComplaints required |
 | `ic` | Insurance Claims | Insurance | Marks insuranceClaims required (isInsured=Yes branch) |
-| `hf` | Historical Flooding | Environmental Issues | Marks hasBeenFlooded required |
-| `nd` | Neighbour Development | Notices | Marks neighbourDevelopment required |
+| `nd` | Neighbour Development | Notices | Adds sef25Ref to neighbourDevelopment (already required via NTS) |
 | `mi` | Material Issue | Additional Information | Marks otherMaterialIssue required |
 | `tr` | Title Restrictions | Ownership (Freehold) | Adds titleRestrictions field to freehold branch |
 
+### Existing fields with sef25Ref only (no separate overlay needed)
+
+| Field | Path | sef25Ref | Notes |
+|-------|------|----------|-------|
+| `hasBeenFlooded` | `environmentalIssues.flooding.historicalFlooding.hasBeenFlooded` | E1.2 | Already required and rendered via NTS flooding section |
+
 All fields use `sef25Ref` for reference codes.
 
 ---
 
-## 1. Supply Costs (`sc`)
+## Pre-existing overlays (detail)
 
-### 1a. Private Water Cost
+### 1. Supply Costs (`sc`)
+
+#### 1a. Private Water Cost
 
 **Trigger:** Show when `propertyPack.waterAndDrainage.water.mainsWater.yesNo` = `"No"`
 
 **Path:** `propertyPack.waterAndDrainage.water.mainsWater.associatedCost`
 
-**UI:** Render alongside the existing "How is water supplied?" details field.
+**UI:** Render alongside the existing "How is water supplied?" details field. First ask if there are costs, then show amount and frequency if Yes.
 
 | Field | Path (relative) | Type | Validation | UI Element |
 |-------|-----------------|------|------------|------------|
-| Cost (£) | `associatedCost.amount` | `number` | Required | Numeric input |
-| Payment frequency | `associatedCost.frequency` | `string` | Required, enum | Dropdown |
+| Has costs? | `associatedCost.hasCost` | `string` | Required, enum | Yes/No radio |
+| Cost (£) | `associatedCost.amount` | `number` | Required when Yes | Numeric input |
+| Payment frequency | `associatedCost.frequency` | `string` | Required when Yes, enum | Dropdown |
 
 **Frequency enum values:** `"Per month"`, `"Per year"`
 
-**Ref:** `U1.1` (amount: `U1.1.1`, frequency: `U1.1.2`)
+**Ref:** `U1.1` (hasCost: `U1.1.1`, amount: `U1.1.2`, frequency: `U1.1.3`)
 
-### 1b. Private Sewerage Cost
+#### 1b. Private Sewerage Cost
 
 **Trigger:** Show when `propertyPack.waterAndDrainage.drainage.mainsFoulDrainage.yesNo` = `"No"` or `"Not known"`
 
 **Path:** `propertyPack.waterAndDrainage.drainage.mainsFoulDrainage.associatedCost`
 
-**UI:** Render alongside the existing off-mains drainage system questions.
-
-| Field | Path (relative) | Type | Validation | UI Element |
-|-------|-----------------|------|------------|------------|
-| Cost (£) | `associatedCost.amount` | `number` | Required | Numeric input |
-| Payment frequency | `associatedCost.frequency` | `string` | Required, enum | Dropdown |
-
-**Frequency enum values:** `"Per month"`, `"Per year"`
-
-**Ref:** `U1.2` (amount: `U1.2.1`, frequency: `U1.2.2`)
+**UI:** Same hasCost pattern as water cost above.
 
----
+**Ref:** `U1.2` (hasCost: `U1.2.1`, amount: `U1.2.2`, frequency: `U1.2.3`)
 
-## 2. Parking Permit Cost (`pc`)
+### 2. Parking Permit Cost (`pc`)
 
 **Trigger:** Show when `propertyPack.parking.controlledParking.yesNo` = `"Yes"`
 
 **Path:** `propertyPack.parking.controlledParking.costOfPermitFrequency`
 
-**UI:** Render alongside the existing cost of permit field (previously titled "Annual cost of permit (£)", now retitled to "Cost of permit (£)"). The frequency dropdown clarifies whether the cost amount is monthly or annual.
+**UI:** Render alongside the existing cost of permit field. The frequency dropdown clarifies whether the cost amount is monthly or annual.
 
 | Field | Path (relative) | Type | Validation | UI Element |
 |-------|-----------------|------|------------|------------|
@@ -77,24 +84,15 @@ All fields use `sef25Ref` for reference codes.
 
 **Frequency enum values:** `"Per month"`, `"Per year"`
 
-**Note:** The existing `annualCostOfPermit` numeric field remains unchanged. The new frequency field sits beside it to indicate whether the entered amount is per month or per year.
-
 **Ref:** `P1.1`
 
----
-
-## 3. Property Hazards (`ph`)
+### 3. Property Hazards (`ph`)
 
-**Trigger:** Always shown (no conditional trigger — these are standalone questions within Specialist Issues).
+**Trigger:** Always shown (standalone questions within Specialist Issues).
 
 **Path prefix:** `propertyPack.specialistIssues`
 
-All 4 fields follow the same pattern:
-
-- **Initial question:** Yes/No radio/toggle
-- **If "Yes":** Show a required free-text "Give details" field
-
-### Fields
+All 4 fields follow the same pattern: Yes/No, if Yes show required details.
 
 | Property | Title | sef25Ref |
 |----------|-------|----------|
@@ -103,29 +101,11 @@ All 4 fields follow the same pattern:
 | `damageToFlooringOrStaircases` | Is there any damage to flooring and/or staircases? | H1.3 |
 | `knownAreasInPoorCondition` | Are there any known areas in poor condition (internal or external)? | H1.4 |
 
-### Data shape per field
-
-```json
-// When "No":
-{ "yesNo": "No" }
-
-// When "Yes":
-{ "yesNo": "Yes", "details": "Free text description..." }
-```
-
-### Validation
-
-- `yesNo` is required (enum: `["Yes", "No"]`)
-- When `yesNo` = `"Yes"`, `details` is required (string, minLength: 1)
-- When `yesNo` = `"No"`, `details` should not be shown or submitted
-
-### UI pattern
-
-These follow the identical pattern to existing specialist issues (dry rot, asbestos, subsidence, health & safety). Render them the same way — group them under "Hazards and Known Issues" within the Specialist Issues section.
-
 ---
 
-## 4. Dropped Kerb (`dk`)
+## New overlays (detail)
+
+### 4. Dropped Kerb (`dk`)
 
 **Trigger:** Always shown within Parking section.
 
@@ -139,7 +119,7 @@ These follow the identical pattern to existing specialist issues (dry rot, asbes
 
 ---
 
-## 5. Private Right of Way (`rw`)
+### 5. Private Right of Way (`rw`)
 
 **Trigger:** Always shown within Rights & Informal Arrangements, alongside the existing public right of way question.
 
@@ -154,26 +134,14 @@ These follow the identical pattern to existing specialist issues (dry rot, asbes
 
 **Ref:** `R1.1` (yesNo: `R1.1.1`, details: `R1.1.2`)
 
-### Data shape
-
-```json
-// When "No":
-{ "yesNo": "No" }
-
-// When "Yes":
-{ "yesNo": "Yes", "details": "Description of private right of way..." }
-```
-
 ---
 
-## 6. Storm, Fire or Flood Damage (`sd`)
+### 6. Storm, Fire or Flood Damage (`sd`)
 
 **Trigger:** Always shown within Environmental Issues section.
 
 **Path:** `propertyPack.environmentalIssues.stormFireFloodDamage`
 
-**UI:** Yes/No, if Yes show details. Render under "Environmental & Structural Information" or "Specialist Issues".
-
 | Field | Path (relative) | Type | Validation | UI Element |
 |-------|-----------------|------|------------|------------|
 | Damage? | `stormFireFloodDamage.yesNo` | `string` | Required, enum | Yes/No radio |
@@ -181,23 +149,13 @@ These follow the identical pattern to existing specialist issues (dry rot, asbes
 
 **Ref:** `E1.1` (yesNo: `E1.1.1`, details: `E1.1.2`)
 
-### Data shape
-
-```json
-// When "No":
-{ "yesNo": "No" }
-
-// When "Yes":
-{ "yesNo": "Yes", "details": "Details of storm/fire/flood damage..." }
-```
-
 ---
 
-## 7. Solar Panel Lease Costs (`lc`)
+### 7. Solar Panel Lease Costs (`lc`)
 
-**Trigger:** Show when `propertyPack.utilities.solarPanels.panelsOwnedOutright.yesNo` = `"No"` (panels are leased).
+**Trigger:** Show when `propertyPack.electricity.solarPanels.panelsOwnedOutright.yesNo` = `"No"` (panels are leased).
 
-**Path:** `propertyPack.utilities.solarPanels.panelsOwnedOutright.associatedCost`
+**Path:** `propertyPack.electricity.solarPanels.panelsOwnedOutright.associatedCost`
 
 **UI:** Render alongside existing lease details. First ask if there are costs, then show amount and frequency if Yes.
 
@@ -211,19 +169,9 @@ These follow the identical pattern to existing specialist issues (dry rot, asbes
 
 **Ref:** `S1.1` (hasCost: `S1.1.1`, amount: `S1.1.2`, frequency: `S1.1.3`)
 
-### Data shape
-
-```json
-// When no costs:
-{ "hasCost": "No" }
-
-// When costs exist:
-{ "hasCost": "Yes", "amount": 50, "frequency": "Per month" }
-```
-
 ---
 
-## 8. Warranties & Guarantees Upfront (`wg`)
+### 8. Warranties & Guarantees Upfront (`wg`)
 
 **Trigger:** Always shown when overlay is loaded. Displayed upfront regardless of `hasValidGuaranteesOrWarranties` value.
 
@@ -231,8 +179,6 @@ These follow the identical pattern to existing specialist issues (dry rot, asbes
 
 **UI:** For SEF25 upfront, show all 7 warranty categories as simple Yes/No questions. No details or "Years Remaining" needed at this stage — the law firm picks up details later.
 
-### Fields (all Yes/No only)
-
 | Property | Title | sef25Ref |
 |----------|-------|----------|
 | `newHomeWarranty` | New Home Warranty (NHBC or similar) | W1.1 |
@@ -247,47 +193,41 @@ These follow the identical pattern to existing specialist issues (dry rot, asbes
 
 ---
 
-## 9. Upfront Existing Fields
-
-The following existing fields have extension overlays that add `sef25Ref` and `required` arrays, making them selectively available for SEF25 upfront forms.
-
-### Disputes & Complaints (`dc`)
-
-**Path:** `propertyPack.disputesAndComplaints.hasDisputesAndComplaints`
-
-**Ref:** `D1.1` — "Have any disputes or complaints occurred, regarding this property, a property nearby, or their use?"
-
-### Insurance Claims (`ic`)
+### 9. Insurance Claims (`ic`)
 
 **Path:** `propertyPack.insurance.insuranceClaims` (inside `isInsured = "Yes"` branch)
 
-**Ref:** `I1.1` — "Have you made any buildings insurance claims?"
-
-**Note:** The field is inside the `isInsured = "Yes"` oneOf branch. The overlay marks it required within that branch.
-
-### Historical Flooding (`hf`)
+**Ref:** `I1.1` (yesNo: `I1.1.1`) — "Have you made any buildings insurance claims?"
 
-**Path:** `propertyPack.environmentalIssues.flooding.historicalFlooding.hasBeenFlooded`
+**Note:** The overlay marks insuranceClaims required within the `isInsured = "Yes"` oneOf branch.
 
-**Ref:** `E1.2` — "Has the property been flooded in the last 5 years?"
+---
 
-### Neighbour Development (`nd`)
+### 10. Neighbour Development (`nd`)
 
 **Path:** `propertyPack.notices.neighbourDevelopment`
 
 **Ref:** `N1.1` — "Is the seller aware of any proposals to develop property or land nearby?"
 
-### Material Issue (`mi`)
+**Note:** `neighbourDevelopment` is already required via `ntsRequired` at the notices level. The `nd` overlay adds `sef25Ref` and `ntsRef` annotations so the field is identifiable as SEF25-relevant.
+
+---
+
+### 11. Material Issue (`mi`)
 
 **Path:** `propertyPack.additionalInformation.otherMaterialIssue`
 
-**Ref:** `M1.1` — "Are you aware of any other material issue or information which may affect the average person's decision to proceed?"
+**Ref:** `M1.1` (yesNo: `M1.1.1`) — "Are you aware of any other material issue or information which may affect the average person's decision to proceed?"
 
-### Title Restrictions (`tr`)
+---
+
+### 12. Title Restrictions (`tr`)
 
 **Path:** `propertyPack.ownership.ownershipsToBeTransferred[Freehold].titleRestrictions`
 
-**Ref:** `T1.1` — "Are there any known restrictions on the title?" (Yes/No + details if Yes, modelled on `leaseRestrictions` for leasehold)
+**Ref:** `T1.1` (yesNo: `T1.1.1`, details: `T1.1.2`) — "Are there any known restrictions on the title?"
+
+New field on the freehold ownership branch, modelled on `leaseRestrictions` for leasehold. Yes/No + details if Yes.
 
 ---
 
@@ -330,7 +270,7 @@ const validator = getValidator(schemaId, sef25Extensions);
 | Insurance claims | `isInsured.yesNo` = `"Yes"` (via `ic` overlay) |
 | Neighbour development | Always (via `nd` overlay) |
 | Other material issue | Always (via `mi` overlay) |
-| Title restrictions | Always (via `tr` overlay) |
+| Title restrictions | Always (via `tr` overlay, freehold only) |
 
 ---
 
@@ -394,7 +334,7 @@ The flooding and planning tasks should be stepped up to their parent section lev
   overlay: "ic",
 },
 {
-  name: "Material information",
+  name: "Additional material information",
   checkName: "sef25-additionalInformation",
   path: "/propertyPack/additionalInformation",
   category: "listing",

package/package.json

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