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 in .chglog/config.yml.

Use dated development versions such as 2026.10.7.dev1 before mandation. Follow the package release instructions to update the package version, validate it and publish a GitHub prerelease. A Git tag alone does not make a release available to the viewer.

After fetching published release tags, regenerate the changelog with:

git fetch origin --tags
git-chglog -o CHANGELOG.md

Review and commit the changelog separately using the project's conventional commit prefixes.

Preserve the old viewer URLs

Do not delete or rename the pages in docs/. They preserve established links by redirecting visitors to equivalent pages in the replacement viewer. Keep GitHub Pages serving main → /docs. Assets and downloads remain at their existing URLs.

During the transition, the site workflow injects redirects into the existing HTML and commits the result. It does not rebuild the old site. Each page keeps its original content, a canonical link, an automatic redirect and a visible link to its replacement. JavaScript preserves query strings and anchors; the no-JavaScript refresh goes to the equivalent page without preserving query strings.

After the published redirects have been checked, disable the old site workflow and retire the renderer separately. Keep docs/ and its redirects. Record the last pre-redirect commit before publishing so its pages can be restored if needed. Changes to the new viewer must continue to support these destination URLs.