This repository contains data specifications used to submit planning application data.
It is an initiative led by the Ministry of Housing, Communities and Local Government aiming to standardise the data you provide when a planning application is submitted.
The specification is made up of these elements:
- applications - these define what is required for a given application type, for example 'householder'
- modules - groupings of fields focused on a specific subject. For example 'agent details'
- components - resuable 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'
These elements are then used to generate the following outputs
- information models for each module
- compiled specifications for each application type and sub-type
- a spreadsheet view of each application type
If you are new to the repository, start with how the specification fits together.
The main command line entry point is spec.py.
Find applications that use a module
python spec.py find applications-with-module <module_ref>Find modules used by an application
python spec.py find modules-in-application <application_ref>Find where a field is used
python spec.py find field-usage <field_ref>Find where a component is used
python spec.py find component-usage <component_ref>Summarise decision-stage needs coverage
python spec.py decision summaryList covered needs as well
python spec.py decision summary --listPreferred grouped commands
Return matching 2025 form URLs for an application type or subtype
python spec.py form-analysis urls <application_type>List matching 2025 forms for an application type or subtype
python spec.py form-analysis list <application_type>Show core details for a 2025 form by reference
python spec.py form-analysis show <form_ref>List analysed 2025 forms that include a module
python spec.py form-analysis for-module <module_ref>List analysed 2025 modules found in a form
python spec.py form-analysis modules <form_ref>These form commands use the analysed 2025 forms data under data/analysis/. They are not derived from the canonical specification model.
Older shortcut commands still work:
python spec.py form-url <application_type>
python spec.py forms <application_type>
python spec.py form <form_ref>
python spec.py module-forms <module_ref>
python spec.py form-modules <form_ref>Print the completeness summary
python spec.py completeness summaryPrint the completeness summary with row-level detail
python spec.py completeness summary --verbosePrint the in-scope and out-of-scope split
python spec.py completeness scopeYou can get involved by:
- raising and commenting on issues
- participating in discussions around applications, modules and codelists
To find out more about the background of the the project you can visit the planning application project page.
For help with the terminology used on this page, visit our glossary of terms.
Below is the list of official application types that we have produced specifications for. Where a more specific classification is needed, the canonical application type codelist now uses a light parent/child hierarchy in a single dataset.
We are prioritising the application types that lead to housing delivery.
| Application type | Child type |
|---|---|
| Approval (discharge) of conditions | |
| Full planning permission | |
| Householder planning application | |
| Lawful development certificate | Existing use of the site |
| Lawful development certificate | Prospective use of the site |
| Lawful development certificate | Proposed work to a listed building |
| Listed building consent | |
| Non-material amendment | |
| Outline planning | All matters reserved |
| Outline planning | Some matters reserved |
| Permission in principle | |
| Planning permission for relevant demolition in a conservation area | |
| Prior approval | Larger Home Extension |
| Prior approval | Additional storeys |
| Removal/variation of conditions (S73) | |
| Reserved matters | |
| Technical details consent |
The application types we have not yet included in these specifications are
- Additional environmental approval to extend the duration of a planning permission
- Certificate of alternative appropriate development
- Change of use planning application
- Circular 14/90 Overhead lines
- Footpath diversion
- Hazardous Substances Consent
- Land Drainage Consent
- Mineral extraction or associated development
- Mineral planning applications
- Modification of conditions relating to construction working hours
- Modification or discharge of a Section 106 planning obligation
- Nationally Significant Infrastructure Projects (NSIPs)
- Public Service Infrastructure applications
- Regulation 3 planning application
- Regulation 4 planning application
- Review of mineral permission (ROMP)
- Transport and works act order
- Waste development
It is important that these specifications work for everyone that needs them (such as software vendors, planning officers, analysts and policymakers). For that to happen we need yor 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.
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 have made 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