Skip to main content

​
Prerequisites

Before installing Digital Planning Data schemas, ensure you have:
  • Node.js 16+ or compatible runtime
  • PNPM 8.6.6+ (for development)
  • A JSON Schema validation library (recommended: ajv or jsonschema)
While PNPM is used for development of the schemas themselves, you can use npm, yarn, or pnpm in your own project.

​
Installation Methods

Choose the installation method that best fits your use case:

Hosted Schema

Direct reference via URL - no installation required

Local Clone

Clone repository for development and customization

Local Package

Build and install as a package dependency

​
Method 1: Hosted Schema Files

The simplest method - reference schemas directly from GitHub Pages.

​
Usage

Schemas are hosted at: 
https://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schemas/<SCHEMA>.json

​
URL Structure

  • VERSION: Use @next for latest, or specific version like 0.7.7
  • SCHEMA: One of application, prototypeApplication, preApplication, postSubmissionApplication, postSubmissionPublishedApplication, or enforcement

​
Example URLs

# Latest application schema
https://theopensystemslab.github.io/digital-planning-data-schemas/@next/schemas/application.json

# Specific version
https://theopensystemslab.github.io/digital-planning-data-schemas/0.7.7/schemas/application.json

# Enforcement schema
https://theopensystemslab.github.io/digital-planning-data-schemas/@next/schemas/enforcement.json

​
Install Validation Dependencies

npm install ajv ajv-formats

​
Implementation Example

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

const SCHEMA_BASE_URL = 'https://theopensystemslab.github.io/digital-planning-data-schemas/@next/schemas';

async function validateApplication(data: unknown) {
  // Fetch schema
  const response = await fetch(`${SCHEMA_BASE_URL}/application.json`);
  const schema = await response.json();

  // Create validator with format support
  const ajv = addFormats(new Ajv({ allowUnionTypes: true }));
  const validate = ajv.compile(schema);

  // Validate data
  const isValid = validate(data);
  
  if (!isValid) {
    console.error('Validation errors:', validate.errors);
    return false;
  }
  
  return true;
}
Always pin to a specific version in production to avoid breaking changes from @next.

​
Method 2: Clone Repository

Clone the repository for development, testing, or contribution.
1

Clone the repository

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

Install dependencies

pnpm install
If you don’t have PNPM installed globally:
npm install -g [email protected]
3

Build schemas and examples

pnpm build
This command:
  • Generates JSON schemas from TypeScript types using ts-json-schema-generator
  • Creates JSON example files from TypeScript example data
  • Outputs schemas to /schemas directory
  • Outputs examples to /examples directory
4

Verify installation

Run the test suite to ensure everything is working:
pnpm test
This validates all schemas against all examples using both jsonschema and ajv libraries.

​
Directory Structure

After building, your directory will contain: 
digital-planning-data-schemas/
├── schemas/              # Generated JSON Schema files
│   ├── application.json
│   ├── prototypeApplication.json
│   ├── preApplication.json
│   ├── postSubmissionApplication.json
│   ├── postSubmissionPublishedApplication.json
│   └── enforcement.json
├── types/                # TypeScript type definitions
│   ├── schemas/
│   │   ├── application/
│   │   ├── enforcement/
│   │   └── shared/
│   └── ...
├── examples/             # Generated JSON examples
│   ├── application/
│   │   ├── planningPermission/
│   │   ├── priorApproval/
│   │   └── lawfulDevelopmentCertificate/
│   └── ...
└── tests/                # Test suites

​
Using Local Schemas

import applicationSchema from './digital-planning-data-schemas/schemas/application.json';
import type { Application } from './digital-planning-data-schemas/types/schemas/application';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

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

const myApplication: Application = {
  // Your application data
};

if (!validate(myApplication)) {
  console.error(validate.errors);
}

​
Method 3: Install as Local Package

Build and install the schemas as a package in your project.
1

Clone and build package

git clone https://github.com/theopensystemslab/digital-planning-data-schemas.git
cd digital-planning-data-schemas
pnpm install
pnpm package
The pnpm package command:
  1. Runs pnpm build to generate schemas
  2. Compiles TypeScript with pnpm compile
  3. Copies .d.ts declaration files to /types
  4. Creates digital-planning-data-schemas-{version}.tgz
  5. Cleans up temporary files
2

Copy package to your project

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

Install the package

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

Install validation dependencies

npm install ajv ajv-formats

​
Package Exports

The package provides the following exports: 
{
  "exports": {
    "./types/*": "./types/*",
    "./schemas/*": "./schemas/*",
    "./examples/*": "./examples/*"
  }
}

​
Import Examples

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

​
Validation Setup

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

// addFormats is required for UUID, email, datetime, etc.
const ajv = addFormats(new Ajv({ 
  allowUnionTypes: true,
  strict: true,
  validateFormats: true
}));

const validate = ajv.compile(applicationSchema);

export function validateApplication(data: unknown): boolean {
  const isValid = validate(data);
  
  if (!isValid) {
    console.error('Validation errors:', validate.errors);
  }
  
  return isValid;
}

​
Using jsonschema Library

import { Validator, Schema } from 'jsonschema';
import applicationSchema from 'digital-planning-data-schemas/schemas/application.json';

const validator = new Validator();

export function validateApplication(data: unknown) {
  const result = validator.validate(data, applicationSchema as Schema);
  
  if (result.errors.length > 0) {
    console.error('Validation errors:', result.errors);
    return false;
  }
  
  return true;
}

​
Development Workflow

If you’re contributing to or extending the schemas:

​
Available Scripts

# Build schemas from TypeScript types
pnpm build-schema

# Build JSON examples from TypeScript examples
pnpm build-json-examples

# Build both schemas and examples
pnpm build

# Run tests
pnpm test

# Type checking
pnpm check

# Lint code
pnpm lint

# Fix linting issues
pnpm fix

# Create package
pnpm package

​
Modifying Schemas

1

Edit TypeScript types

Modify files in /types/schemas/ directory.Types are annotated using JSDoc comments which become schema descriptions:
/**
 * @title Application
 * @description The root specification for a planning application
 */
export interface Application {
  data: ApplicationData;
  metadata: Metadata;
}
2

Rebuild schemas

pnpm build-schema
This runs the build script which uses ts-json-schema-generator:
pnpm ts-json-schema-generator \
  --path "types/schemas/application/*.ts" \
  --out "schemas/application.json" \
  --type "Application" \
  --id "@next" \
  --no-top-ref
3

Test changes

pnpm test

​
Adding Examples

1

Create TypeScript example

Add a file to /examples/<SCHEMA>/data/ with exported example data:
// examples/application/data/myExample.ts
import { Application } from '../../../types/schemas/application';

export const myExample: Application = {
  data: {
    // Your example data
  },
  // ...
};
2

Build JSON examples

pnpm build-json-examples
This automatically generates corresponding JSON files in the root of /examples.
3

Validate example

pnpm test
Confirms your example payload validates against the schema.

​
Version Management

The current version is defined in package.json: 
{
  "name": "digital-planning-data-schemas",
  "version": "0.7.7"
}

​
Publishing a New Version

1

Update version

Increment the version in package.json:
{
  "version": "0.7.8"
}
2

Create pull request

Open a PR against the main branch with the version change.
3

Automatic publication

On merge, the publish.yml GitHub Action will:
  • Update the dist branch
  • Create a GitHub release
  • Publish via GitHub Pages at the new version URL

​
Troubleshooting

Install PNPM globally:
npm install -g [email protected]
Or use npx:
npx [email protected] install
Ensure you’re using TypeScript ~5.5.4:
pnpm add -D typescript@~5.5.4
Make sure you’ve added format support to AJV:
import addFormats from 'ajv-formats';
const ajv = addFormats(new Ajv({ allowUnionTypes: true }));
Check your tsconfig.json includes:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

​
Next Steps

Quick Start

Start validating applications immediately

API Implementation

Learn API implementation guidelines

Browse Examples

Explore real-world planning application examples

View Latest Schema

See the latest schema documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us