Integration Methods

Overview

There are three main approaches to integrate Digital Planning Data schemas into your application, each suited for different use cases and development workflows.

Integration Options

Hosted Schema
Clone Repository
NPM Package

Reference Hosted Schema Files

The simplest integration method is to reference the hosted schema files directly. This approach requires no installation and always points to a specific version.

const schemaUrl = `https://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schemas/<SCHEMA>.json`;

Example: Fetching the Application Schema

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

Available Schemas:

application.json - Full planning applications
preApplication.json - Pre-application submissions
prototypeApplication.json - Prototype applications
postSubmissionApplication.json - Post-submission data
postSubmissionPublishedApplication.json - Published applications
enforcement.json - Enforcement cases

Replace <VERSION> with a specific version number or use @next for the latest development version.

Clone and Reference Locally

For development environments or when you need offline access, clone the repository and reference schemas locally.

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

Then reference schemas programmatically in your code:

import applicationSchema from './digital-planning-data-schemas/schemas/application.json';
import {Application} from './digital-planning-data-schemas/types/schemas/application';

// Use the schema for validation
function validateApplication(data: unknown): data is Application {
  // Your validation logic here
  return true;
}

Benefits:

Full access to TypeScript types
Offline development capability
Direct control over version updates
Access to examples and tests

Install as NPM Package

For production applications, install the schemas as a local package. This approach provides the best integration with TypeScript projects.

Build the package

In the schemas repository:

pnpm package

This creates a file named digital-planning-data-schemas-{version}.tgz.

Copy to your project

Copy the .tgz file to your project directory:

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

Install the package

Install using npm or add to package.json:Option 1: NPM Install

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

Option 2: package.json

{
  "dependencies": {
    "digital-planning-data-schemas": "file:digital-planning-data-schemas-0.7.7.tgz"
  }
}

Then run:

npm install

Import and use

Import TypeScript types and schemas:

// Import 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 schemas
import applicationSchema from 'digital-planning-data-schemas/schemas/application.json';

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

Package Exports:

{
  "exports": {
    "./types/*": "./types/*",
    "./schemas/*": "./schemas/*",
    "./examples/*": "./examples/*"
  }
}

Version Management

The schemas follow semantic versioning. The repository structure maintains versions:

main branch: Reflects the @next version (development)
dist branch: Contains released versions with documentation
GitHub Releases: Tagged versions available at specific URLs

// Use a specific version
const v0_7_7 = 'https://theopensystemslab.github.io/digital-planning-data-schemas/0.7.7/schemas/application.json';

// Use the latest development version
const latest = 'https://theopensystemslab.github.io/digital-planning-data-schemas/@next/schemas/application.json';

Schema Validation Libraries

The schemas are JSON Schema Draft 07 compliant and work with standard validation libraries:

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

// Initialize AJV with format support
const ajv = addFormats(new Ajv({allowUnionTypes: true}));
const validate = ajv.compile(applicationSchema);

// Validate data
const isValid = validate(applicationData);
if (!isValid) {
  console.error(validate.errors);
}

When using AJV, remember to include ajv-formats for proper validation of email, date-time, UUID, and other format types used in the schemas.

Next Steps

Validation Patterns

Learn how to validate data against the schemas

TypeScript Types

Discover how to use TypeScript types effectively

Examples

Explore real-world implementation examples

API Implementation

Guidelines for implementing schemas in APIs

Get Started

Core Concepts

Schemas

Usage Guide

Overview

Integration Options

Reference Hosted Schema Files

Clone and Reference Locally

Install as NPM Package

Version Management

Schema Validation Libraries

Next Steps

Validation Patterns

TypeScript Types

Examples

API Implementation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Schemas

Usage Guide

​Overview

​Integration Options

​Reference Hosted Schema Files

​Clone and Reference Locally

​Install as NPM Package

​Version Management

​Schema Validation Libraries

​Next Steps

Validation Patterns

TypeScript Types

Examples

API Implementation

Build docs developers (and LLMs) love

Overview

Integration Options

Reference Hosted Schema Files

Clone and Reference Locally

Install as NPM Package

Version Management

Schema Validation Libraries

Next Steps