Planning application data specification

This repository contains the data specifications that define how planning application data should be structured.

It is an initiative led by the Ministry of Housing, Communities and Local Government aiming to standardise and increase the value of planning application data.

To find out more about the background to the project, visit the planning application project page.

What the specification covers

The specification covers what needs to be:

• submitted - it defines what information is needed for each type of planning application and how it should be structured
• recorded about the application - it defines everything a planning authority must record about a planning application, including the application itself, how it has been processed and the decisions made
• made available as open data - it defines what data can and must be made available as open data for the benefit of others

See which application types are currently in scope.

The data model

The specification is made up of these elements:

• applications - these define what is required for a given application type, for example 'householder'. See which application types are in scope.
• modules - groupings of fields focused on a specific subject. For example 'agent details'
• components - reusable groups of fields, or substructures that are used by multiple modules. For example 'supporting documents'
• fields - these define the specific fields, setting expectations for the field. For example 'decision date'
• codelists - these set the allowable values for a given field, for example 'parking space type'
• datasets - these cover how the submitted and recorded information should be structured, for example 'site'

There is more information on how the specification is structured in the /documentation folder.

Other ways to access the specification

The canonical specification in this repository is used to generate the following outputs:

• a specification viewer for an easier way to view and explore the specification
• compiled markdown representations of each application type showing what is expected to be submitted for each application type
• spreadsheets for each application type so that people can use those to perform analysis tasks
• JSON schemas for each application type, which can be used to build services

If you are new to the repository, start with how the specification fits together.

---

CLI

spec.py is a command line tool for exploring this repository.

Use it when you want to inspect the specification, check how specification elements are connected, or run the small set of project reports that are maintained with the repository.

Run commands from the repository root:

python spec.py --help

The CLI has three main command groups:

• inspect for the canonical specification model
• report for repository summaries and progress reports
• analysis for useful side datasets, such as the 2025 forms analysis

For usage examples and the command reference, see spec CLI.

---

We need your help

It is important that these specifications work for everyone who needs them, such as software vendors, planning officers, analysts and policymakers. For that to happen we need your feedback, questions and contributions.

You can comment on any of the items in this repository and we encourage you to help us work through outstanding issues.

You can get involved by:

• raising and commenting on issues
• participating in discussions around applications, modules and codelists
• joining the regular community sessions, the date of the next event can be found on the project page

Maintaining a CHANGELOG

We maintain a CHANGELOG using git-chglog. This groups commits by type and into releases. Types are configurable and set in .chglog/config.yml. Releases are handled by git tag.

If you make a PR with a number of commits (following conventional commits) and want to update the CHANGELOG, run

git tag -a v{version_number} -m "{release description}"
# then
git-chglog -o CHANGELOG.md