feat(appeals): S20 data model updates (#100)

bryn-pins · NHAL22 · fabfab-kc · web-flow · commit f8b09b6022eb · 2025-06-04T09:04:16.000+01:00
* feat(appeals): make event address optional

* update appeal_document.documentType enumeration list

* add new S20 fields, adds doctype to commands

* generating types

---------

Co-authored-by: NHAL22 &lt;113360585+NHAL22@users.noreply.github.com&gt;
Co-authored-by: Fabio Fabrizio &lt;fabio.fabrizio@kinandcarta.com&gt;
diff --git a/docs/appeal-document.md b/docs/appeal-document.md
@@ -594,6 +594,7 @@ The type of document, used for exchange, migrations and consumption from the app
 | `"rule6WitnessesEvidence"`        |             |
 | `"environmentalAssessment"`       |             |
 | `"appealNotification"`            |             |
+| `"historicEnglandConsultation"`   |             |
 | `null`                            |             |
 
 ## sourceSystem
diff --git a/docs/appeal-event.md b/docs/appeal-event.md
@@ -16,11 +16,11 @@
 | [eventStartDateTime](#eventstartdatetime)           | `string`  | Required | cannot be null | [Appeal Event](appeal-event-properties-eventstartdatetime.md "appeal-event.schema.json#/properties/eventStartDateTime")           |
 | [eventEndDateTime](#eventenddatetime)               | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-eventenddatetime.md "appeal-event.schema.json#/properties/eventEndDateTime")               |
 | [notificationOfSiteVisit](#notificationofsitevisit) | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-notificationofsitevisit.md "appeal-event.schema.json#/properties/notificationOfSiteVisit") |
-| [addressLine1](#addressline1)                       | `string`  | Required | cannot be null | [Appeal Event](appeal-event-properties-addressline1.md "appeal-event.schema.json#/properties/addressLine1")                       |
+| [addressLine1](#addressline1)                       | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-addressline1.md "appeal-event.schema.json#/properties/addressLine1")                       |
 | [addressLine2](#addressline2)                       | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-addressline2.md "appeal-event.schema.json#/properties/addressLine2")                       |
-| [addressTown](#addresstown)                         | `string`  | Required | cannot be null | [Appeal Event](appeal-event-properties-addresstown.md "appeal-event.schema.json#/properties/addressTown")                         |
+| [addressTown](#addresstown)                         | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-addresstown.md "appeal-event.schema.json#/properties/addressTown")                         |
 | [addressCounty](#addresscounty)                     | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-addresscounty.md "appeal-event.schema.json#/properties/addressCounty")                     |
-| [addressPostcode](#addresspostcode)                 | `string`  | Required | cannot be null | [Appeal Event](appeal-event-properties-addresspostcode.md "appeal-event.schema.json#/properties/addressPostcode")                 |
+| [addressPostcode](#addresspostcode)                 | `string`  | Required | can be null    | [Appeal Event](appeal-event-properties-addresspostcode.md "appeal-event.schema.json#/properties/addressPostcode")                 |
 | Additional Properties                               | Any       | Optional | can be null    |                                                                                                                                   |
 
 ## eventId
@@ -295,7 +295,7 @@ First line of address for the event site
 
 * Type: `string`
 
-* cannot be null
+* can be null
 
 * defined in: [Appeal Event](appeal-event-properties-addressline1.md "appeal-event.schema.json#/properties/addressLine1")
 
@@ -337,7 +337,7 @@ Town / City of the event address
 
 * Type: `string`
 
-* cannot be null
+* can be null
 
 * defined in: [Appeal Event](appeal-event-properties-addresstown.md "appeal-event.schema.json#/properties/addressTown")
 
@@ -385,7 +385,7 @@ Postal code of the event address
 
 * Type: `string`
 
-* cannot be null
+* can be null
 
 * defined in: [Appeal Event](appeal-event-properties-addresspostcode.md "appeal-event.schema.json#/properties/addressPostcode")
 
diff --git a/docs/appeal-s78.md b/docs/appeal-s78.md
@@ -79,6 +79,8 @@
 | [reasonForNeighbourVisits](#reasonforneighbourvisits)                                 | `string`  | Required | can be null    | [Appeal S78 Case](appeal-s78-properties-reasonforneighbourvisits.md "appeal-s78.schema.json#/properties/reasonForNeighbourVisits")                                 |
 | [affectedListedBuildingNumbers](#affectedlistedbuildingnumbers)                       | `array`   | Required | can be null    | [Appeal S78 Case](appeal-s78-properties-affectedlistedbuildingnumbers.md "appeal-s78.schema.json#/properties/affectedListedBuildingNumbers")                       |
 | [changedListedBuildingNumbers](#changedlistedbuildingnumbers)                         | `array`   | Required | can be null    | [Appeal S78 Case](appeal-s78-properties-changedlistedbuildingnumbers.md "appeal-s78.schema.json#/properties/changedListedBuildingNumbers")                         |
+| [preserveGrantLoan](#preservegrantloan)                                               | `boolean` | Optional | can be null    | [Appeal S78 Case](appeal-s78-properties-preservegrantloan.md "appeal-s78.schema.json#/properties/preserveGrantLoan")                                               |
+| [consultHistoricEngland](#consulthistoricengland)                                     | `boolean` | Optional | can be null    | [Appeal S78 Case](appeal-s78-properties-consulthistoricengland.md "appeal-s78.schema.json#/properties/consultHistoricEngland")                                     |
 | [appellantCostsAppliedFor](#appellantcostsappliedfor)                                 | `boolean` | Required | can be null    | [Appeal S78 Case](appeal-s78-properties-appellantcostsappliedfor.md "appeal-s78.schema.json#/properties/appellantCostsAppliedFor")                                 |
 | [lpaCostsAppliedFor](#lpacostsappliedfor)                                             | `boolean` | Required | can be null    | [Appeal S78 Case](appeal-s78-properties-lpacostsappliedfor.md "appeal-s78.schema.json#/properties/lpaCostsAppliedFor")                                             |
 | [agriculturalHolding](#agriculturalholding)                                           | `boolean` | Required | can be null    | [Appeal S78 Case](appeal-s78-properties-agriculturalholding.md "appeal-s78.schema.json#/properties/agriculturalHolding")                                           |
@@ -2092,6 +2094,46 @@ A list of changed listed building IDs from Historic England
 
 `string[]`
 
+## preserveGrantLoan
+
+A grant or loan has been made to preserve the listed building
+
+> Only available in S20 cases
+
+`preserveGrantLoan`
+
+* is optional
+
+* Type: `boolean`
+
+* can be null
+
+* defined in: [Appeal S78 Case](appeal-s78-properties-preservegrantloan.md "appeal-s78.schema.json#/properties/preserveGrantLoan")
+
+### preserveGrantLoan Type
+
+`boolean`
+
+## consultHistoricEngland
+
+Are Historic England to be consulted?
+
+> Only available in S20 cases
+
+`consultHistoricEngland`
+
+* is optional
+
+* Type: `boolean`
+
+* can be null
+
+* defined in: [Appeal S78 Case](appeal-s78-properties-consulthistoricengland.md "appeal-s78.schema.json#/properties/consultHistoricEngland")
+
+### consultHistoricEngland Type
+
+`boolean`
+
 ## appellantCostsAppliedFor
 
 Indicates if the appellant has applied for costs
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "pins-data-model",
-  "version": "1.10.1",
+  "version": "1.10.2",
   "description": "JSON Schemas for the Planning Inspectorate's Data Model",
   "main": "src/index.js",
   "type": "module",
diff --git a/pins_data_model/models/model_appeal_document.py b/pins_data_model/models/model_appeal_document.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  appeal-document.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:46+00:00
 
 from __future__ import annotations
 
@@ -116,6 +116,7 @@ class DocumentType(Enum):
     rule6WitnessesEvidence = "rule6WitnessesEvidence"
     environmentalAssessment = "environmentalAssessment"
     appealNotification = "appealNotification"
+    historicEnglandConsultation = "historicEnglandConsultation"
     NoneType_None = None
 
 
diff --git a/pins_data_model/models/model_appeal_event.py b/pins_data_model/models/model_appeal_event.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  appeal-event.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
@@ -95,23 +95,23 @@ class AppealEvent(BaseModel):
     """
     The date third-parties were informed of the site visit event
     """
-    addressLine1: str = Field(..., examples=["96 The Avenue"])
+    addressLine1: str | None = Field(..., examples=["96 The Avenue"])
     """
     First line of address for the event site
     """
     addressLine2: str | None = None
     """
     Second line of address for the event site
     """
-    addressTown: str = Field(..., examples=["Maidstone"])
+    addressTown: str | None = Field(..., examples=["Maidstone"])
     """
     Town / City of the event address
     """
     addressCounty: str | None = Field(..., examples=["Kent"])
     """
     County of the event address
     """
-    addressPostcode: str = Field(..., examples=["MD21 5XY"])
+    addressPostcode: str | None = Field(..., examples=["MD21 5XY"])
     """
     Postal code of the event address
     """
diff --git a/pins_data_model/models/model_appeal_event_estimate.py b/pins_data_model/models/model_appeal_event_estimate.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  appeal-event-estimate.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_appeal_has.py b/pins_data_model/models/model_appeal_has.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  appeal-has.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_appeal_representation.py b/pins_data_model/models/model_appeal_representation.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  appeal-representation.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_appeal_s78.py b/pins_data_model/models/model_appeal_s78.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  appeal-s78.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:46+00:00
 
 from __future__ import annotations
 
@@ -651,6 +651,14 @@ class AppealS78Case(BaseModel):
     """
     A list of changed listed building IDs from Historic England
     """
+    preserveGrantLoan: bool | None = None
+    """
+    A grant or loan has been made to preserve the listed building
+    """
+    consultHistoricEngland: bool | None = None
+    """
+    Are Historic England to be consulted?
+    """
     appellantCostsAppliedFor: bool | None = None
     """
     Indicates if the appellant has applied for costs
diff --git a/pins_data_model/models/model_dart_response.py b/pins_data_model/models/model_dart_response.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  dart-response.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_entraid.py b/pins_data_model/models/model_entraid.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  entraid.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_folder.py b/pins_data_model/models/model_folder.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  folder.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_gettimesheets_response.py b/pins_data_model/models/model_gettimesheets_response.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  gettimesheets-response.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_listed_building.py b/pins_data_model/models/model_listed_building.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  listed-building.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_listed_buildings.py b/pins_data_model/models/model_listed_buildings.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  listed-buildings.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:46+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_nsip_document.py b/pins_data_model/models/model_nsip_document.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  nsip-document.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_nsip_exam_timetable.py b/pins_data_model/models/model_nsip_exam_timetable.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  nsip-exam-timetable.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:46+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_nsip_project.py b/pins_data_model/models/model_nsip_project.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  nsip-project.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_nsip_project_update.py b/pins_data_model/models/model_nsip_project_update.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  nsip-project-update.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_nsip_representation.py b/pins_data_model/models/model_nsip_representation.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  nsip-representation.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:46+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_nsip_subscription.py b/pins_data_model/models/model_nsip_subscription.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  nsip-subscription.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_pins_inspector.py b/pins_data_model/models/model_pins_inspector.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  pins-inspector.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_pins_lpa.py b/pins_data_model/models/model_pins_lpa.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  pins-lpa.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_s51_advice.py b/pins_data_model/models/model_s51_advice.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  s51-advice.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/pins_data_model/models/model_service_user.py b/pins_data_model/models/model_service_user.py
@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  service-user.schema.json
-#   timestamp: 2025-05-08T14:17:31+00:00
+#   timestamp: 2025-06-03T09:08:45+00:00
 
 from __future__ import annotations
 
diff --git a/schemas/appeal-document.schema.json b/schemas/appeal-document.schema.json
@@ -211,6 +211,7 @@
         "rule6WitnessesEvidence",
         "environmentalAssessment",
         "appealNotification",
+        "historicEnglandConsultation",
         null
       ],
       "description": "The type of document, used for exchange, migrations and consumption from the appeal back-office system"
diff --git a/schemas/appeal-event.schema.json b/schemas/appeal-event.schema.json
@@ -96,7 +96,7 @@
       "description": "The date third-parties were informed of the site visit event"
     },
     "addressLine1": {
-      "type": "string",
+      "type": ["string", "null"],
       "examples": ["96 The Avenue"],
       "description": "First line of address for the event site"
     },
@@ -105,7 +105,7 @@
       "description": "Second line of address for the event site"
     },
     "addressTown": {
-      "type": "string",
+      "type": ["string", "null"],
       "examples": ["Maidstone"],
       "description": "Town / City of the event address"
     },
@@ -115,7 +115,7 @@
       "description": "County of the event address"
     },
     "addressPostcode": {
-      "type": "string",
+      "type": ["string", "null"],
       "examples": ["MD21 5XY"],
       "description": "Postal code of the event address"
     }
diff --git a/schemas/appeal-s78.schema.json b/schemas/appeal-s78.schema.json
@@ -698,6 +698,16 @@
       "description": "A list of changed listed building IDs from Historic England",
       "$comment": "Only available in S78 cases"
     },
+    "preserveGrantLoan": {
+      "type": ["boolean", "null"],
+      "description": "A grant or loan has been made to preserve the listed building",
+      "$comment": "Only available in S20 cases"
+    },
+    "consultHistoricEngland": {
+      "type": ["boolean", "null"],
+      "description": "Are Historic England to be consulted?",
+      "$comment": "Only available in S20 cases"
+    },
     "appellantCostsAppliedFor": {
       "type": ["boolean", "null"],
       "description": "Indicates if the appellant has applied for costs",
diff --git a/schemas/commands/appellant-submission.schema.json b/schemas/commands/appellant-submission.schema.json
diff --git a/schemas/commands/lpa-questionnaire-s78.schema.json b/schemas/commands/lpa-questionnaire-s78.schema.json
diff --git a/schemas/commands/lpa-questionnaire.schema.json b/schemas/commands/lpa-questionnaire.schema.json
diff --git a/src/enums.cjs b/src/enums.cjs
diff --git a/src/enums.d.ts b/src/enums.d.ts
diff --git a/src/enums.js b/src/enums.js
diff --git a/src/index.cjs b/src/index.cjs
diff --git a/src/schemas.d.ts b/src/schemas.d.ts
diff --git a/tests/appeals/appeal-event.test.js b/tests/appeals/appeal-event.test.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "pins-data-model",`
`3`		`- "version": "1.10.1",`
	`3`	`+ "version": "1.10.2",`
`4`	`4`	`"description": "JSON Schemas for the Planning Inspectorate's Data Model",`
`5`	`5`	`"main": "src/index.js",`
`6`	`6`	`"type": "module",`