chore: more annotations (#61)

theopensystemslab · Oct 26, 2023 · af70822 · af70822
1 parent 0c498ad
commit af70822
Show file tree

Hide file tree

Showing 10 changed files with 125 additions and 19 deletions.
diff --git a/examples/data/ldcE.ts b/examples/data/ldcE.ts
@@ -5,7 +5,7 @@ export const validLDCE: Schema = {
     application: {
       type: {
         value: 'ldc.existing',
-        description: 'Lawful Development Certificate - Existing',
+        description: 'Lawful Development Certificate - Existing use',
       },
       fee: {
         calculated: 206,

diff --git a/examples/data/ldcP.ts b/examples/data/ldcP.ts
@@ -5,7 +5,7 @@ export const validLDCP: Schema = {
     application: {
       type: {
         value: 'ldc.proposed',
-        description: 'Lawful Development Certificate - Proposed',
+        description: 'Lawful Development Certificate - Proposed use',
       },
       fee: {
         calculated: 103,

diff --git a/examples/validLawfulDevelopmentCertificateExisting.json b/examples/validLawfulDevelopmentCertificateExisting.json
@@ -3,7 +3,7 @@
     "application": {
       "type": {
         "value": "ldc.existing",
-        "description": "Lawful Development Certificate - Existing"
+        "description": "Lawful Development Certificate - Existing use"
       },
       "fee": {
         "calculated": 206,

diff --git a/examples/validLawfulDevelopmentCertificateProposed.json b/examples/validLawfulDevelopmentCertificateProposed.json
@@ -3,7 +3,7 @@
     "application": {
       "type": {
         "value": "ldc.proposed",
-        "description": "Lawful Development Certificate - Proposed"
+        "description": "Lawful Development Certificate - Proposed use"
       },
       "fee": {
         "calculated": 103,

diff --git a/schema/schema.json b/schema/schema.json
@@ -222,6 +222,7 @@
           "additionalProperties": false,
           "properties": {
             "govPay": {
+              "description": "GOV.UK Pay payment reference number",
               "type": "string"
             }
           },
@@ -264,7 +265,7 @@
           "additionalProperties": false,
           "properties": {
             "description": {
-              "const": "Lawful Development Certificate - Proposed",
+              "const": "Lawful Development Certificate - Proposed use",
               "type": "string"
             },
             "value": {
@@ -282,7 +283,7 @@
           "additionalProperties": false,
           "properties": {
             "description": {
-              "const": "Lawful Development Certificate - Existing",
+              "const": "Lawful Development Certificate - Existing use",
               "type": "string"
             },
             "value": {
@@ -296,6 +297,42 @@
           ],
           "type": "object"
         },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "const": "Lawful Development Certificate - Continue an existing use",
+              "type": "string"
+            },
+            "value": {
+              "const": "ldc.existing.regularise",
+              "type": "string"
+            }
+          },
+          "required": [
+            "value",
+            "description"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "const": "Lawful Development Certificate - Lawful not to comply with a condition or limitation",
+              "type": "string"
+            },
+            "value": {
+              "const": "ldc.condition",
+              "type": "string"
+            }
+          },
+          "required": [
+            "value",
+            "description"
+          ],
+          "type": "object"
+        },
         {
           "additionalProperties": false,
           "properties": {
@@ -1104,6 +1141,24 @@
     "FileType": {
       "$id": "#FileType",
       "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "const": "Evidence for application fee exemption - disability",
+              "type": "string"
+            },
+            "value": {
+              "const": "applicant.disability.evidence",
+              "type": "string"
+            }
+          },
+          "required": [
+            "value",
+            "description"
+          ],
+          "type": "object"
+        },
         {
           "additionalProperties": false,
           "properties": {
@@ -2539,6 +2594,7 @@
           "required": [
             "known"
           ],
+          "title": "Energy Performance Certificate",
           "type": "object"
         },
         "address": {
@@ -2583,6 +2639,7 @@
           "type": "object"
         },
         "localAuthorityDistrict": {
+          "description": "Current and historic UK Local Authority Districts that contain this address sourced from planning.data.gov.uk/dataset/local-authority-district",
           "items": {
             "type": "string"
           },
@@ -2618,6 +2675,7 @@
       "required": [
         "EPC",
         "address",
+        "constraints",
         "localAuthorityDistrict",
         "region",
         "titleNumber",
@@ -2806,9 +2864,11 @@
       "description": "Address information for sites with a known address sourced from Ordnance Survey AddressBase Premium",
       "properties": {
         "latitude": {
+          "description": "Latitude coordinate in EPSG:4326 (WGS84)",
           "type": "number"
         },
         "longitude": {
+          "description": "Longitude coordinate in EPSG:4326 (WGS84)",
           "type": "number"
         },
         "organisation": {
@@ -2837,15 +2897,21 @@
           "type": "string"
         },
         "uprn": {
+          "maxLength": 12,
+          "title": "Unique Property Reference Number",
           "type": "string"
         },
         "usrn": {
+          "maxLength": 8,
+          "title": "Unique Street Reference Number",
           "type": "string"
         },
         "x": {
+          "description": "Easting coordinate in British National Grid (OSGB36)",
           "type": "number"
         },
         "y": {
+          "description": "Northing coordinate in British National Grid (OSGB36)",
           "type": "number"
         }
       },
@@ -17212,9 +17278,11 @@
       "description": "Address information for sites without a known Unique Property Reference Number (UPRN)",
       "properties": {
         "latitude": {
+          "description": "Latitude coordinate in EPSG:4326 (WGS84)",
           "type": "number"
         },
         "longitude": {
+          "description": "Longitude coordinate in EPSG:4326 (WGS84)",
           "type": "number"
         },
         "source": {
@@ -17225,9 +17293,11 @@
           "type": "string"
         },
         "x": {
+          "description": "Easting coordinate in British National Grid (OSGB36)",
           "type": "number"
         },
         "y": {
+          "description": "Northing coordinate in British National Grid (OSGB36)",
           "type": "number"
         }
       },
@@ -18002,6 +18072,7 @@
           "type": "object"
         },
         "localAuthorityDistrict": {
+          "description": "Current and historic UK Local Authority Districts that contain this address sourced from planning.data.gov.uk/dataset/local-authority-district",
           "items": {
             "type": "string"
           },
@@ -18018,13 +18089,14 @@
         "address",
         "region",
         "localAuthorityDistrict",
-        "type"
+        "type",
+        "constraints"
       ],
       "type": "object"
     },
     "UKRegion": {
       "$id": "#UKRegion",
-      "description": "UK regions sourced from planning.data.gov.uk/dataset/region, where London is a proxy for the Greater London Authority (GLA) area",
+      "description": "The UK region that contains this address sourced from planning.data.gov.uk/dataset/region, where London is a proxy for the Greater London Authority (GLA) area",
       "enum": [
         "North East",
         "North West",
@@ -18619,7 +18691,7 @@
       "description": "Vehicle parking types"
     }
   },
-  "description": "The root schema for an application generated by a digital planning service",
+  "description": "The root specification for a planning application in England generated by a digital planning service",
   "properties": {
     "data": {
       "additionalProperties": false,

diff --git a/types/Schema.ts b/types/Schema.ts
@@ -10,7 +10,7 @@ import {File} from './schema/File';
 
 /**
  * @title Digital Planning Application
- * @description The root schema for an application generated by a digital planning service
+ * @description The root specification for a planning application in England generated by a digital planning service
  */
 export interface Schema {
   data: {

diff --git a/types/enums/ApplicationTypes.ts b/types/enums/ApplicationTypes.ts
@@ -3,8 +3,12 @@
  */
 export const ApplicationTypes = {
   ldc: 'Lawful Development Certificate',
-  'ldc.proposed': 'Lawful Development Certificate - Proposed',
-  'ldc.existing': 'Lawful Development Certificate - Existing',
+  'ldc.proposed': 'Lawful Development Certificate - Proposed use',
+  'ldc.existing': 'Lawful Development Certificate - Existing use',
+  'ldc.existing.regularise':
+    'Lawful Development Certificate - Continue an existing use',
+  'ldc.condition':
+    'Lawful Development Certificate - Lawful not to comply with a condition or limitation',
   pa: 'Prior Approval',
   'pa.part1.classA': 'Prior Approval - Larger extension to a house',
   'pa.part1.classAA': 'Prior Approval - Adding storeys to a house',
@@ -48,7 +52,7 @@ export const ApplicationTypes = {
   'pa.part20.classZA':
     'Prior Approval - Demolish buildings and build homes in their place',
   pp: 'Planning Permission',
-  'pp.full.householder': 'Planning Permission - Full householder',
+  'pp.full.householder': 'Planning Permission - Full householder', // "Planning permission for a home"
   'pp.full.householder.retro':
-    'Planning Permission - Full householder retrospective',
+    'Planning Permission - Full householder retrospective', // "Retrospective planning permission for a home"
 };
diff --git a/types/enums/FileTypes.ts b/types/enums/FileTypes.ts
@@ -2,6 +2,8 @@
  * Values of `file.type`
  */
 export const FileTypes = {
+  'applicant.disability.evidence':
+    'Evidence for application fee exemption - disability',
   'property.drawing.elevation': 'Elevations - existing',
   'property.drawing.floorPlan': 'Floor plan - existing',
   'property.drawing.roofPlan': 'Roof plan - existing',

diff --git a/types/schema/data/Application.ts b/types/schema/data/Application.ts
@@ -20,7 +20,7 @@ export interface ApplicationFee {
   calculated: number;
   payable: number;
   exemption: {
-    disability: boolean; // @todo add application.fee.exemption.disability.reason & applicant.disability.evidence (file)
+    disability: boolean; // @todo add application.fee.exemption.disability.reason
     resubmission: boolean; // @todo add application.resubmission.original.applicationReference & application.resubmission.originalReference.appeal
   };
   reduction: {
@@ -29,8 +29,10 @@ export interface ApplicationFee {
     sports: boolean;
   };
   reference?: {
-    // @todo require when payable > 0
-    govPay: string;
+    /**
+     * @description GOV.UK Pay payment reference number
+     */
+    govPay: string; // @todo require when payable > 0
   };
 }
 

diff --git a/types/schema/data/Property.ts b/types/schema/data/Property.ts
@@ -11,7 +11,7 @@ export type Property = UKProperty | LondonProperty;
 
 /**
  * @id #UKRegion
- * @description UK regions sourced from planning.data.gov.uk/dataset/region, where London is a proxy for the Greater London Authority (GLA) area
+ * @description The UK region that contains this address sourced from planning.data.gov.uk/dataset/region, where London is a proxy for the Greater London Authority (GLA) area
  */
 export type UKRegion =
   | 'North East'
@@ -31,13 +31,16 @@ export type UKRegion =
 export interface UKProperty {
   address: ProposedAddress | OSAddress;
   region: UKRegion;
+  /**
+   * @description Current and historic UK Local Authority Districts that contain this address sourced from planning.data.gov.uk/dataset/local-authority-district
+   */
   localAuthorityDistrict: string[];
   type: PropertyType;
   boundary?: {
     site: GeoJSON;
     area: Area;
   };
-  constraints?: {
+  constraints: {
     planning: PlanningConstraint[];
   };
 }
@@ -52,6 +55,9 @@ export interface LondonProperty extends UKProperty {
     known: 'Yes' | 'No';
     number?: string;
   };
+  /**
+   * @title Energy Performance Certificate
+   */
   EPC: {
     known:
       | 'Yes'
@@ -68,9 +74,21 @@ export interface LondonProperty extends UKProperty {
  */
 export interface SiteAddress {
   title: string;
+  /**
+   * @description Easting coordinate in British National Grid (OSGB36)
+   */
   x: number;
+  /**
+   * @description Northing coordinate in British National Grid (OSGB36)
+   */
   y: number;
+  /**
+   * @description Latitude coordinate in EPSG:4326 (WGS84)
+   */
   latitude: number;
+  /**
+   * @description Longitude coordinate in EPSG:4326 (WGS84)
+   */
   longitude: number;
 }
 
@@ -87,7 +105,15 @@ export interface ProposedAddress extends SiteAddress {
  * @description Address information for sites with a known address sourced from Ordnance Survey AddressBase Premium
  */
 export interface OSAddress extends SiteAddress {
+  /**
+   * @title Unique Property Reference Number
+   * @maxLength 12
+   */
   uprn: string;
+  /**
+   * @title Unique Street Reference Number
+   * @maxLength 8
+   */
   usrn: string;
   pao: string;
   street: string;