@planning-inspectorate/data-model 1.11.0

package/.azure/ci.yml

@@ -0,0 +1,60 @@
+trigger:
+  branches:
+    include:
+      - main # run on main before build
+      # trigger for merge queue branches
+      - gh-readonly-queue/*
+
+pr:
+  branches:
+    include:
+      - '*'
+
+resources:
+  repositories:
+    - repository: templates
+      type: github
+      endpoint: Planning-Inspectorate
+      name: Planning-Inspectorate/common-pipeline-templates
+      ref: refs/tags/release/3.18.2
+
+extends:
+  template: stages/wrapper_ci.yml@templates
+  parameters:
+    skipAzureAuth: true
+    validationJobs:
+      - name: Run Checks
+        steps:
+          - template: ../steps/node_script.yml
+            parameters:
+              nodeVersion: 22
+              script: npm ci
+          - template: ../steps/node_script.yml
+            parameters:
+              nodeVersion: 22
+              script: npm run commitlint
+          - template: ../steps/node_script.yml
+            parameters:
+              nodeVersion: 22
+              script: npm run lint
+          - template: ../steps/node_script.yml
+            parameters:
+              nodeVersion: 22
+              script: npm run format-check
+          - template: ../steps/node_script.yml
+            parameters:
+              nodeVersion: 22
+              script: npm run gen
+          - template: ../steps/node_script.yml
+            parameters:
+              nodeVersion: 22
+              script: node --test
+          - script: |
+              git status --porcelain
+              if [[ `git status --porcelain` ]]; then
+                # Changes - generated files out of date! Show changes:
+                git diff
+                # fail pipeline run
+                exit 1
+              fi
+            displayName: Check no generated files out of date

package/.azure/release.yml

@@ -0,0 +1,57 @@
+parameters:
+  - name: dryRun
+    displayName: Dry Run
+    type: boolean
+    default: false
+
+trigger: none
+pr: none
+
+resources:
+  repositories:
+    - repository: templates
+      type: github
+      endpoint: Planning-Inspectorate
+      name: Planning-Inspectorate/common-pipeline-templates
+      ref: refs/tags/release/3.23.0
+  pipelines:
+    - pipeline: pr
+      source: PR
+      trigger:
+        branches:
+          include:
+            - main
+
+variables:
+  - group: data-model-release
+  - name: dryRunFlag
+    ${{ if eq(parameters.dryRun, true) }}:
+      value: '--dry-run'
+    ${{ if eq(parameters.dryRun, false) }}:
+      value: ''
+
+pool: pins-odt-agent-pool
+
+jobs:
+  - deployment: Release
+    displayName: Release
+    environment: 'NPM'
+    strategy:
+      runOnce:
+        deploy:
+          steps:
+            - download: none
+            - checkout: self
+            - template: steps/node_script.yml@templates
+              parameters:
+                nodeVersion: 22
+                script: npm ci
+            - template: steps/node_script.yml@templates
+              parameters:
+                nodeVersion: 22
+                script: npx semantic-release --branches main --tag-format '${version}' ${{ variables.dryRunFlag }}
+                environmentVariables:
+                  GH_TOKEN: $(GITHUB_TOKEN)
+                  NPM_TOKEN: $(NPM_TOKEN)
+    workspace:
+      clean: all

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/' # Location of package manifests
+    schedule:
+      interval: 'weekly'

package/.husky/install.mjs

@@ -0,0 +1,7 @@
+try {
+	const husky = (await import('husky')).default;
+	console.log(husky());
+} catch (e) {
+	// may fail if husky isn't installed, e.g. in a production scenario
+	console.log('husky installed failed', e);
+}

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged && npm run format

package/.prettierignore

@@ -0,0 +1,11 @@
+node_modules
+package.json
+package-lock.json
+README.md
+*.njk
+.env*
+docs/
+src/enums.d.ts
+src/enums.js
+src/schemas.d.ts
+*.cjs

package/.prettierrc

@@ -0,0 +1,19 @@
+{
+	"printWidth": 120,
+	"tabWidth": 2,
+	"singleQuote": true,
+	"useTabs": true,
+	"semi": true,
+	"trailingComma": "none",
+	"bracketSpacing": true,
+	"arrowParens": "always",
+	"plugins": [],
+	"overrides": [
+		{
+			"files": "*.json",
+			"options": {
+				"useTabs": false
+			}
+		}
+	]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Planning Inspectorate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# Data Model
+
+JSON Schemas for the Planning Inspectorate's Data Model.
+
+All messages over the enterprise service bus are in Data Model compliant formats, the schema's in this repository defined those formats.
+
+## Rules of engagement
+* Schema names should use the singular form (for example, `service-user` rather than `service-users`).
+* Messages broadcast over the service bus must be pre-validated against the schema.
+* Each service bus topic corresponds to one schema. 
+* Each message encompasses the complete state of an entity (as defined by [ECST](https://blogs.mulesoft.com/api-integration/strategy/event-carried-state-messages/)) and does not delineate specific changes (the delta). 
+* Consumers must support processing related messages received through different topics regardless of the order in which they are sent.
+* Values required by the Data Model cannot be null, while optional values must be null if they have no value. 
+
+## Schema Changes
+
+**Always consult a Data Architect about the proposed change - who will consider the change in terms of affect on other services and continuity with the overall data model.**
+
+Since we are using these schemas across a distributed system we must ensure backwards and forwards compatibility. This enables systems to adopt new schema versions independently of one another. Also, consumers don't need to know the schema version of the messages they have received, as it should validate against any version.
+
+Backwards compatibility ensures that messages using a newer schema version can be understood and processed by consumers that have not been updated to support the new version.
+
+Forwards compatibility ensures that messages using an older schema version can be understood and processed by consumers that have been updated to support a newer schema version.
+
+### Rules
+
+To ensure compatibility, the following rules must be followed:
+
+1. No fields can be removed from the schema
+2. No fields can be removed from the `required` list
+3. Optional fields must support the `null` type
+4. Fields cannot be renamed
+5. Any new fields must be optional
+6. Any enum changes must only add options
+7. `additionalProperties` must always be true
+
+### Examples
+
+Given a simple schema at v1:
+
+```json
+{
+    "type": "object",
+    "title": "Book",
+    "required": ["id", "title"]
+    "additionalProperties": true,
+    "properties": {
+        "id": {
+            "type": "integer",
+            "description": "The unique identifier"
+        },
+        "title": {
+            "type": "string",
+            "description": "The title or name of this book"
+        },
+        "blurb": {
+            "type": ["string", "null"],
+            "description": "The blurb"
+        },
+        "category": {
+            "type": ["string", "null"],
+            "description": "The top-level category",
+            "enum": [
+                "fiction",
+                "non-fiction",
+                null
+            ]
+        }
+    }
+}
+```
+
+An example valid message at v1 could be:
+
+```json
+{
+    "id": 85347,
+    "title": "Mastering the Rubik's Cube",
+    "blurb": null,
+    "category": "non-fiction"
+}
+```
+
+Let's make a v2 schema:
+
+```json
+{
+    "type": "object",
+    "title": "Book",
+    "required": ["id", "title"]
+    "additionalProperties": true,
+    "properties": {
+        "id": {
+            "type": "integer",
+            "description": "The unique identifier"
+        },
+        "title": {
+            "type": "string",
+            "description": "The title or name of this book"
+        },
+        "blurb": {
+            "type": ["string", "null"],
+            "description": "The blurb"
+        },
+        "category": {
+            "type": ["string", "null"],
+            "description": "The top-level category",
+            "enum": [
+                "fiction",
+                "non-fiction",
+                "ai-generated",
+                null
+            ]
+        },
+        "subCategory": {
+            "type": ["string", "null"],
+            "description": "The sub category",
+            "enum": [
+                "manuals",
+                "stories",
+                null
+            ]
+        }
+    }
+}
+```
+
+Two changes have been made:
+ 1. a new enum valid for `category`
+ 2. a new field, `subCategory`
+
+Now the original v1 message still validates against this schema. And a new v2 message, for example:
+
+```json
+{
+    "id": 85347,
+    "title": "Mastering the Rubik's Cube",
+    "blurb": null,
+    "category": "non-fiction",
+    "subCategory": "manuals"
+}
+```
+
+validates against the _old schema_ and the new schema!
+
+
+## Structure
+
+* `docs`: generated documentation from the JSON schemas
+* `pins_data_model`: Python library code (inc. generated Pydantic models)
+* `schemas`: JSON schemas
+* `src`: Node.js library code
+
+## Commands
+
+There are some messages, primarily used from Front Office to Back Office systems that aren't strictly compliant to the model, since the Front Office doesn't author the data. These are known as _commands_ (or submissions) and are usually a combination or subset of Data Model entities in a single message.
+
+## Schemas
+
+The schemas in this repository are written in jsonc (JSON with comments), and can be parsed with [node-jsonc-parser](https://github.com/Microsoft/node-jsonc-parser), or [jsonc-parser](https://github.com/NickolaiBeloguzov/jsonc-parser) for Python.
+
+>While we'd prefer to use something with a standard, such as JSON5, this has less support with our current workflows. The jsonc format is the same format that VSCode uses for settings.
+
+## Node.js Usage
+
+To use these schemas in a Node project, add this repo as a dependency (with a particular tag or commit as the version):
+
+`npm i -s Planning-Inspectorate/data-model#some-tag-or-commit`
+
+Then import as required:
+
+```es6
+import {loadAllSchemas} from 'pins-data-model';
+```
+
+or to import enum constants, for example:
+
+```es6
+import { APPEAL_CASE_STATUS } from 'pins-data-model';
+
+if (someAppeal.status === APPEAL_CASE_STATUS.COMPLETE) {
+    console.log(`we're done!`);
+}
+```
+
+To upgrade to a different version, simply doing npm command does not seem to get the correct version, so we need to first uninstall and then reinstall. You can do this by running:
+
+`npm uninstall pins-data-model && npm prune && npm i -s github:Planning-Inspectorate/data-model#some-tag-or-commit`
+
+### Tests
+
+We are starting to add js tests to the models using node test runner
+
+These are run automatically by the pipeline and can be run locally with:
+
+`node --test`
+
+Please continue to expand this test suite going forward to help avoid breaking changes impacting consumers of the model
+
+## Python usage
+
+To use these schemas in a Python project, add this repo as a dependency (with a particular tag or commit as the version):
+
+`pip install git+https://github.com/Planning-Inspectorate/data-model@task/python-setup#egg=pins_data_model`
+
+install deps from requirements.txt: `pip install -r requirements.txt`
+
+> you may want to run python in a virtual environment (handle python version/deps separately from system installed)
+
+create a venv in a folder (.venv is git ignored): `python -m venv .venv` 
+
+you can specify a python version with: `python3.13.2 -m venv .venv`
+
+activate it before running any python script: `source .venv/bin/activate`
+
+deactivate once finished: `deactivate`
+
+```python
+from pins_data_model.load_schemas import load_all_schemas
+
+schemas = load_all_schemas()
+print(schemas)
+```
+
+## Contributing
+
+Once you have updated the schemas, before committing, ensure the generated code/documentation is up to date by running:
+
+`npm run gen`
+
+and
+
+`python pins_data_model/gen_models.py`
+
+Commits must follow conventional commits, and the commit types will be used by semantic-release to determine the next version number. For example `feat` commits will result in a minor version bump, while `fix` commits will result in a patch version bump.
+
+The package will be released automatically using semantic-release, on merge to main. This will include a git tag for the release, and publishing to NPM.

package/commitlint.config.js

@@ -0,0 +1,8 @@
+export default {
+	extends: ['@commitlint/config-conventional'],
+	// ignore commits from dependabot
+	ignores: [
+		(commit) =>
+			(commit.startsWith('chore(deps)') || commit.startsWith('chore(deps-dev)')) && commit.includes('dependabot')
+	]
+};

package/docs/README.md

@@ -0,0 +1,85 @@
+# README
+
+## Top-level Schemas
+
+* [Appeal Document](./appeal-document.md "Schema defining the metadata for appeal documents") – `appeal-document.schema.json`
+
+* [Appeal Event](./appeal-event.md "Schema defining the metadata for appeal events, such as site visits, inquiries, hearings") – `appeal-event.schema.json`
+
+* [Appeal Event Estimate](./appeal-event-estimate.md "All event estimates belong to a case") – `appeal-event-estimate.schema.json`
+
+* [Appeal HAS Case](./appeal-has.md "Schema defining the metadata for an appeal") – `appeal-has.schema.json`
+
+* [Appeal Representation](./appeal-representation.md "Schema defining the metadata for appeal representations, such as statements, third-party comments and final comments") – `appeal-representation.schema.json`
+
+* [Appeal S78 Case](./appeal-s78.md "Schema defining the metadata for an appeal (S78)") – `appeal-s78.schema.json`
+
+* [DaRT API response](./dart-response.md "Schema defining the data returned by the DaRT API") – `dart-response.schema.json`
+
+* [Entra ID User Objects](./entraid.md "A list of users from EntraID") – `entraid.schema.json`
+
+* [Examination Timetable](./nsip-exam-timetable.md "Examination Timetable for an NSIP Project") – `nsip-exam-timetable.schema.json`
+
+* [Folder](./folder.md "Folders can have optional parents") – `folder.schema.json`
+
+* [Get Timesheets API response](./gettimesheets-response.md "Schema defining the data returned by the DaRT API") – `gettimesheets-response.schema.json`
+
+* [Listed Building](./listed-building.md "Delta of listed building data pushed by the ODW") – `listed-building.schema.json`
+
+* [Listed Buildings](./listed-buildings.md "Temporary copy of listed-building to ensure compatibility until ODW is updated") – `listed-buildings.schema.json`
+
+* [NSIP Document](./nsip-document.md "NSIP document schema") – `nsip-document.schema.json`
+
+* [NSIP Project](./nsip-project.md "Subset of Pins Data Model \[Case]") – `nsip-project.schema.json`
+
+* [NSIP Project Update](./nsip-project-update.md "NSIP Project Update (formerly known as Banners)") – `nsip-project-update.schema.json`
+
+* [PINS Inspector](./pins-inspector.md "Inspector attributes as per Horizon") – `pins-inspector.schema.json`
+
+* [PINS LPA](./pins-lpa.md "Local Planning Authority (LPA) attributes as per Horizon") – `pins-lpa.schema.json`
+
+* [Representation](./nsip-representation.md "NSIP Representation schema") – `nsip-representation.schema.json`
+
+* [S51 Advice](./s51-advice.md "Section 51 Advice schema") – `s51-advice.schema.json`
+
+* [Service User](./service-user.md "Service User of the planning inspectorate") – `service-user.schema.json`
+
+* [nsip-subscription](./nsip-subscription.md "Subscribers are a subset of Service Users, part of the PINS Data Model") – `nsip-subscription.schema.json`
+
+## Other Schemas
+
+### Objects
+
+* [Untitled object in Appeal HAS Case](./appeal-has-properties-neighbouringsiteaddresses-items.md) – `appeal-has.schema.json#/properties/neighbouringSiteAddresses/items`
+
+* [Untitled object in Appeal S78 Case](./appeal-s78-properties-neighbouringsiteaddresses-items.md) – `appeal-s78.schema.json#/properties/neighbouringSiteAddresses/items`
+
+* [Untitled object in DaRT API response](./dart-response-properties-neighbouringsiteaddresses-items.md) – `dart-response.schema.json#/properties/neighbouringSiteAddresses/items`
+
+* [Untitled object in Examination Timetable](./nsip-exam-timetable-defs-event.md) – `nsip-exam-timetable.schema.json#/$defs/event`
+
+* [Untitled object in Examination Timetable](./nsip-exam-timetable-defs-line-item.md) – `nsip-exam-timetable.schema.json#/$defs/line-item`
+
+### Arrays
+
+* [Untitled array in Appeal Representation](./appeal-representation-properties-documentids.md "An array of documentIds") – `appeal-representation.schema.json#/properties/documentIds`
+
+* [Untitled array in Examination Timetable](./nsip-exam-timetable-properties-events.md) – `nsip-exam-timetable.schema.json#/properties/events`
+
+* [Untitled array in Examination Timetable](./nsip-exam-timetable-defs-event-properties-eventlineitems.md) – `nsip-exam-timetable.schema.json#/$defs/event/properties/eventLineItems`
+
+* [Untitled array in NSIP Project](./nsip-project-properties-regions.md) – `nsip-project.schema.json#/properties/regions`
+
+* [Untitled array in NSIP Project](./nsip-project-properties-nsipofficerids.md) – `nsip-project.schema.json#/properties/nsipOfficerIds`
+
+* [Untitled array in NSIP Project](./nsip-project-properties-nsipadministrationofficerids.md) – `nsip-project.schema.json#/properties/nsipAdministrationOfficerIds`
+
+* [Untitled array in NSIP Project](./nsip-project-properties-inspectorids.md) – `nsip-project.schema.json#/properties/inspectorIds`
+
+* [Untitled array in Representation](./nsip-representation-properties-attachmentids.md) – `nsip-representation.schema.json#/properties/attachmentIds`
+
+* [Untitled array in S51 Advice](./s51-advice-properties-attachmentids.md) – `s51-advice.schema.json#/properties/attachmentIds`
+
+## Version Note
+
+The schemas linked above follow the JSON Schema Spec version: `http://json-schema.org/draft-07/schema#`