TypeScript Types

types/
├── shared/           # Shared types used across schemas
│   ├── User.ts
│   ├── Metadata.ts
│   ├── Addresses.ts
│   ├── Contacts.ts
│   └── ...
└── schemas/          # Schema-specific types
    ├── application/
    │   ├── index.ts
    │   ├── data/
    │   │   ├── Applicant.ts
    │   │   ├── Property.ts
    │   │   ├── Proposal.ts
    │   │   └── ...
    │   └── enums/
    │       ├── ApplicationTypes.ts
    │       ├── PropertyTypes.ts
    │       └── ...
    └── ...

import type {Application} from 'digital-planning-data-schemas/types/schemas/application';

/**
 * @title Application
 * @description The root specification for a planning application in England
 * generated by a digital planning service
 */
interface Application {
  data: {
    application: ApplicationData;
    user: User;
    applicant: Applicant;
    property: Property;
    proposal: Proposal;
    files?: FilesAsData;
  };
  preAssessment?: PreAssessment;
  responses: Responses;
  files: File[];
  metadata: Metadata;
}

import type {User} from 'digital-planning-data-schemas/types/shared/User';

/**
 * @title User
 * @description The role of the user who completed the application
 */
interface User {
  role: 'applicant' | 'agent' | 'proxy';
}

import type {Applicant, BaseApplicant, Agent} from 'digital-planning-data-schemas/types/schemas/application/data/Applicant';

/**
 * @description The user who completed the application either for themself
 * or on behalf of someone else
 */
type Applicant = BaseApplicant | Agent;

/**
 * @description Information about the user who completed the application
 * for themself, or information about the person who the user applied
 * on behalf of
 */
type BaseApplicant = ContactDetails &
  SiteContact &
  MaintenanceContacts & {
    type: 'individual' | 'company' | 'charity' | 'public' | 'parishCouncil';
    address: UserAddress;
    ownership?: Ownership;
  };

/**
 * @description Information about the agent or proxy who completed
 * the application on behalf of someone else
 */
interface Agent extends BaseApplicant {
  agent: ContactDetails & {address: Address};
}

import type {Metadata, PlanXMetadata, AnyProviderMetadata} from 'digital-planning-data-schemas/types/shared/Metadata';

type Metadata = AnyProviderMetadata | PlanXMetadata;

interface BaseMetadata {
  /** Organisation code from planning.data.gov.uk */
  organisation: string; // maxLength: 4
  /** Unique identifier for this application */
  id: UUID;
  submittedAt: DateTime;
  schema: URL;
}

interface PlanXMetadata extends BaseMetadata {
  source: 'PlanX';
  service: {
    flowId: UUID;
    url: URL;
    files: RequestedFiles;
    fee: FeeExplanation | FeeExplanationNotApplicable;
    enhancements?: Enhancements;
  };
}

import {ApplicationTypes, ApplicationType, ApplicationTypeKeys} from 'digital-planning-data-schemas/types/schemas/application/enums/ApplicationTypes';

// The const object containing all application types
const ApplicationTypes = {
  advertConsent: 'Consent to display an advertisement',
  'ldc.existing': 'Lawful Development Certificate - Existing use',
  'ldc.proposed': 'Lawful Development Certificate - Proposed use',
  'pa.part1.classA': 'Prior Approval - Larger extension to a house',
  'pp.full.householder': 'Planning Permission - Full householder',
  'pp.full.major': 'Planning Permission - Major application',
  // ... many more types
};

// Type-safe keys
type ApplicationTypeKeys = keyof typeof ApplicationTypes;

// Structured type with value and description
type ApplicationType = {
  value: ApplicationTypeKeys;
  description: string;
};

import {ApplicationTypes} from 'digital-planning-data-schemas/types/schemas/application/enums/ApplicationTypes';

// Type-safe application type
const applicationType = {
  value: 'pp.full.householder' as const,
  description: ApplicationTypes['pp.full.householder'],
};

// Get description from value
function getApplicationDescription(key: ApplicationTypeKeys): string {
  return ApplicationTypes[key];
}

console.log(getApplicationDescription('ldc.existing'));
// "Lawful Development Certificate - Existing use"

// From types/shared/utils.ts

/**
 * @format uuid
 */
type UUID = string;

/**
 * @format date-time
 */
type DateTime = string;

/**
 * @format uri
 */
type URL = string;

/**
 * @format email
 */
type Email = string;

import type {Applicant, Agent, BaseApplicant} from 'digital-planning-data-schemas/types/schemas/application/data/Applicant';

function isAgent(applicant: Applicant): applicant is Agent {
  return 'agent' in applicant;
}

function processApplicant(applicant: Applicant) {
  if (isAgent(applicant)) {
    // TypeScript knows applicant is Agent here
    console.log('Agent:', applicant.agent.name);
    console.log('Applicant:', applicant.name);
  } else {
    // TypeScript knows applicant is BaseApplicant here
    console.log('Direct applicant:', applicant.name);
  }
}

import type {Application} from 'digital-planning-data-schemas/types/schemas/application';

const version = process.env['VERSION'] || '@next';

export const planningPermissionFullHouseholder: Application = {
  data: {
    application: {
      type: {
        value: 'pp.full.householder',
        description: 'Planning Permission - Full householder',
      },
      fee: {
        calculated: 258,
        payable: 258,
        category: {
          sixAndSeven: 258,
        },
        exemption: {
          disability: false,
          resubmission: false,
        },
        reduction: {
          sports: false,
          parishCouncil: false,
          alternative: false,
        },
        reference: {
          govPay: 'sandbox-ref-456',
        },
      },
      declaration: {
        accurate: true,
        connection: {
          value: 'none',
        },
      },
      CIL: {
        result: 'notLiable',
        declaration: true,
        s73Application: false,
        existingPermissionPrecedingCIL: false,
        newDwellings: false,
        floorAreaHundredPlus: false,
      },
    },
    user: {
      role: 'proxy',
    },
    applicant: {
      type: 'individual',
      name: {
        first: 'David',
        last: 'Bowie',
      },
      email: '[email protected]',
      phone: {
        primary: 'Not provided by agent',
      },
      address: {
        sameAsSiteAddress: true,
      },
      siteContact: {
        role: 'proxy',
      },
      ownership: {
        interest: 'owner.sole',
        certificate: 'a',
        agriculturalTenants: false,
        declaration: {
          accurate: true,
        },
      },
      agent: {
        name: {
          first: 'Ziggy',
          last: 'Stardust',
        },
        email: '[email protected]',
        phone: {
          primary: '01100 0110 0011',
        },
        address: {
          line1: '40 Stansfield Road',
          line2: 'Brixton',
          town: 'London',
          county: 'Greater London',
          postcode: 'SW9 9RZ',
          country: 'UK',
        },
      },
    },
    // ... more data
  },
  responses: [],
  files: [],
  metadata: {
    organisation: 'LBH',
    id: '81bcaa0f-baf5-4573-ba0a-ea868c573faf',
    source: 'PlanX',
    submittedAt: '2023-10-02T00:00:00.00Z',
    schema: `https://theopensystemslab.github.io/digital-planning-data-schemas/${version}/schemas/application.json`,
    service: {
      flowId: '01e38c5d-e701-4e44-acdc-4d6b5cc3b854',
      url: 'https://www.editor.planx.dev/lambeth/apply-for-planning-permission/preview',
      files: {
        required: ['roofPlan.existing', 'roofPlan.proposed'],
        recommended: ['floorPlan.existing', 'floorPlan.proposed'],
        optional: [],
      },
      fee: {
        calculated: [
          {
            description: 'The fee to apply for planning permission to alter or extend a single home is £258.',
            policyRefs: [
              {
                text: 'UK Statutory Instruments 2023 No. 1197',
                url: 'https://www.legislation.gov.uk/uksi/2023/1197/made',
              },
            ],
          },
        ],
        payable: [
          {
            description: 'The fee to apply for planning permission to alter or extend a single home is £258.',
          },
        ],
      },
    },
  },
};

#!/bin/bash
# From scripts/build-schema.sh

version="${VERSION:-@next}"

dirs=("application" "preApplication" "prototypeApplication")
types=("Application" "PreApplication" "PrototypeApplication")

for i in "${!dirs[@]}"; do
  dir=${dirs[$i]}
  type=${types[$i]}

  pnpm ts-json-schema-generator \
    --path "types/schemas/${dir}/*.ts" \
    --out "schemas/${dir}.json" \
    --type "$type" \
    --id "$version" \
    --no-top-ref
done

/**
 * @title User
 * @description The role of the user who completed the application
 */
export interface User {
  role: 'applicant' | 'agent' | 'proxy';
}

/**
 * @id #Applicant
 * @description The user who completed the application either for themself
 * or on behalf of someone else
 */
export type Applicant = BaseApplicant | Agent;

/**
 * @description Organisation code from planning.data.gov.uk
 * @maxLength 4
 */
organisation: string;

/**
 * @format uuid
 */
type UUID = string;

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "skipLibCheck": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "strict": true,
    "moduleResolution": "node",
    "types": ["node"],
    "paths": {
      "digital-planning-data-schemas/*": ["./node_modules/digital-planning-data-schemas/*"]
    }
  }
}