Skip to main content

​
Overview

This guide will help you quickly integrate Digital Planning Data schemas into your project and validate your first planning application payload.

​
Three Ways to Use the Schemas

There are three main options for integrating with Digital Planning Data schemas:

Hosted Schema

Reference schema files directly from GitHub Pages

Local Clone

Clone the repository and use schemas programmatically

NPM Package

Build and install as a local package in your project

​
Option 1: Reference Hosted Schema

The simplest way to get started is by referencing the hosted schema files directly: 
https://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schemas/<SCHEMA>.json
Replace <VERSION> with a specific version like 0.7.7 or use @next for the latest version. Replace <SCHEMA> with the schema name like application, enforcement, etc.

​
Example: Validate with AJV

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = addFormats(new Ajv({ allowUnionTypes: true }));

// Fetch the schema
const schemaUrl = 'https://theopensystemslab.github.io/digital-planning-data-schemas/@next/schemas/application.json';
const response = await fetch(schemaUrl);
const schema = await response.json();

// Compile the schema
const validate = ajv.compile(schema);

// Validate your data
const applicationData = {
  data: {
    application: { /* ... */ },
    user: { /* ... */ },
    applicant: { /* ... */ },
    property: { /* ... */ },
    proposal: { /* ... */ }
  },
  responses: [],
  files: [],
  metadata: { /* ... */ }
};

const isValid = validate(applicationData);
if (!isValid) {
  console.error('Validation errors:', validate.errors);
}

​
Option 2: Clone Repository

For local development and programmatic access:
1

Clone the repository

git clone https://github.com/theopensystemslab/digital-planning-data-schemas.git
cd digital-planning-data-schemas
2

Install dependencies

Requires PNPM to be available globally.
pnpm install
3

Build the schemas

pnpm build
This generates JSON Schema files in /schemas from the TypeScript interfaces in /types.
4

Use schemas in your code

import applicationSchema from './schemas/application.json';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = addFormats(new Ajv({ allowUnionTypes: true }));
const validate = ajv.compile(applicationSchema);

const isValid = validate(yourApplicationData);

​
Option 3: Install as Package

Create a local package to install in your project:
1

Build the package

pnpm package
This creates a digital-planning-data-schemas-{version}.tgz file.
2

Copy to your project

cp digital-planning-data-schemas-0.7.7.tgz /path/to/your/project/
3

Install in your project

npm install digital-planning-data-schemas-0.7.7.tgz
4

Import types and schemas

// Import TypeScript types
import type { Application } from 'digital-planning-data-schemas/types/schemas/application';
import type { CommentType } from 'digital-planning-data-schemas/types/schemas/postSubmissionApplication/enums/CommentType';

// Import JSON schemas
import applicationSchema from 'digital-planning-data-schemas/schemas/application.json';

// Import example data
import example from 'digital-planning-data-schemas/examples/application/planningPermission/fullHouseholder.json';

​
Validate Your First Application

Let’s validate a planning application using both popular validation libraries: 
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import applicationSchema from './schemas/application.json';

// addFormats() is required for UUID, email, datetime types
const ajv = addFormats(new Ajv({ allowUnionTypes: true }));
const validate = ajv.compile(applicationSchema);

const isValid = validate(applicationData);

if (!isValid) {
  console.error('Validation errors:', validate.errors);
} else {
  console.log('Application is valid!');
}

​
Example Application Data

Here’s a minimal example of a valid planning application: 
const planningApplication: Application = {
  data: {
    application: {
      type: {
        value: 'pp.full.householder',
        description: 'Planning Permission - Full householder'
      },
      fee: {
        calculated: 258,
        payable: 258,
        category: { sixAndSeven: 258 }
      },
      declaration: {
        accurate: true,
        connection: { value: 'none' }
      }
    },
    user: {
      role: 'applicant'
    },
    applicant: {
      type: 'individual',
      name: {
        first: 'John',
        last: 'Smith'
      },
      email: '[email protected]',
      phone: { primary: '01234567890' },
      address: { sameAsSiteAddress: true },
      siteContact: { role: 'applicant' }
    },
    property: {
      address: {
        latitude: 51.4656522,
        longitude: -0.1185926,
        title: '40, STANSFIELD ROAD, LONDON',
        source: 'Ordnance Survey',
        uprn: '100021892955',
        postcode: 'SW9 9RZ'
      },
      boundary: {
        site: {
          type: 'Feature',
          geometry: {
            type: 'Polygon',
            coordinates: [/* GeoJSON coordinates */]
          },
          properties: null
        }
      }
    },
    proposal: {
      description: 'Construction of a single-storey rear extension'
    }
  },
  responses: [],
  files: [],
  metadata: {
    source: 'PlanX',
    submittedAt: '2024-01-15T10:30:00Z'
  }
};
For complete, real-world examples, see the /examples directory in the repository.

​
Available Schemas

The following schemas are currently available:
SchemaDescriptionVersion
application.jsonMain planning application schema@next
prototypeApplication.jsonPrototype application format@next
preApplication.jsonPre-application enquiries@next
postSubmissionApplication.jsonApplications after submission@next
postSubmissionPublishedApplication.jsonPublished applications@next
enforcement.jsonPlanning enforcement notices@next

​
Next Steps

Installation Guide

Detailed installation and setup instructions

Browse Examples

Explore real planning application examples

API Implementation

Learn how to implement the schema in your API

GitHub Repository

View the source code and contribute

​
Testing Your Integration

Run the test suite to verify your setup: 
pnpm test
This runs validation tests using both jsonschema and ajv libraries against all example payloads.

Build docs developers (and LLMs) love

Get started for freeTalk to us