chore: update README and examples (#45)

README.md

@@ -1,74 +1,63 @@
-# Digital Planning Data Schemas
-Welcome to the Digital Planning Data Schemas repository! Here, we are creating and maintaining comprehensive JSON schemas that define the structure and format of Digital Planning services. Our goal is to provide a standardized and consistent way of representing data in the realm of digital planning, enabling seamless integration, efficient data exchange, and improved collaboration among various tools and platforms.
+# Digital Planning Data schemas
+This repository contains [JSON schemas](https://json-schema.org/) to describe Digital Planning services developed by [Open Digital Planning](https://opendigitalplanning.org/).
 
-## Installation
-```shell
-npm install -g [email protected]
-pnpm i
-```
+Our initial schema defines data structures, rules, and validation logic for planning applications - including Lawful Development Certificates, Prior Approval, and Householder Planning Permission - that are being designed and submitted via [PlanX](https://www.planx.uk/). 
+
+Digital Planning Data schemas aim to encourage more interoperability and consistency between systems by offering a central, version controlled standard for documenting and validating planning data. Going forward, we hope that this repository will expand beyond applications to further describe planning reference numbers, site notices, consultations, and more.
 
-## Repository Structure
-Here's an overview of the main directories:
+## Usage
+There's two main options for integrating with Digital Planning Data schemas:
 
-`/schema`: This directory contains the JSON schema files for different aspects of Digital Planning. Each schema is documented and versioned to ensure consistency and traceability.
+1. Reference a hosted schema file directly, like `http://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schema.json` 
 
-`/examples`: Here, you'll find real-world examples illustrating how to use the schemas in various scenarios. These examples provide practical guidance on implementing the schemas in your projects. (TODO)
+2. Clone this repository and reference the local schema files programmatically in your own code using tools that support JSON schema validation
 
-`/types`: This directory holds the TypeScript interfaces which are used to generate the JSON schema.
+For more detailed info on integrating and validating schemas, please refer to the examples and tests in this repo.
 
-`/tests`: This houses test suites and cases to ensure that the schemas are valid, accurate, and capable of handling a variety of scenarios.
+## Repository structure
 
-## Usage
-Integrating our Digital Planning data schemas into your projects is straightforward. You can either directly reference the schema files from this repository or integrate them programmatically using tools that support JSON schema validation.
+`/examples`: Examples of valid payloads for each application type supported by the JSON schema
 
-To reference a schema directly, you can use URLs like the following:
+`/schema`: The main JSON schema file. The `main` branch of this repo will reflect the `@next` version, while historic versions are documented and released on the `dist` branch.
 
-`http://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schema.json`
+`/types`: TypeScript interfaces used to generate the JSON schema.
 
-Alternatively, you can clone the repository to your local environment and use the schema files programmatically in your code.
+`/tests`: Test suites to ensure that the generated schemas and example payloads are valid, accurate, and capable of handling different scenarios.
 
-For more detailed information on integrating and validating schemas, please refer to our examples.
+## Installation
+
+Assumes [PNPM](https://pnpm.io/) is available globally.
+
+```shell
+pnpm i
+```
 
 ## Developing
 The JSON schema is defined using TypeScript interfaces and then generated using the `ts-json-schema-generator` library.
 
-To make changes, update source types and then run `pnpm build` to generate the output JSON file.
+To make changes, update `/types` and then run `pnpm build` to automatically generate the output JSON file under `/schema`.
 
-We use JSDocs to annotate our types, which is also used as part of the schema generation. At a minimum, please try to add the following annotation to all types - 
+Types should be annotated using JSDocs, which will then be read during schema generation. 
 
-```ts
-/**
- * @id Unique identifier
- * @title A helpful title - usually the interface name
- * @description A helpful description of this interface
- */
-```
+Please see the [JSON schema docs](https://json-schema.org/understanding-json-schema/reference/) for a full list of references for various types.
 
-Many additional properties can be provided, such as 
+## Adding examples and tests
 
-```ts
-/**
- * @format e.g. "email", "uuid" - see https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats
- * @minmum Min length
- * @maximum Max length
- * @pattern Regex - see https://json-schema.org/understanding-json-schema/reference/regular_expressions.html#regular-expressions
- */
-```
+Add a TypeScript file to `/examples/data` with at least one exported variable representing an example payload definition.
 
-Please see the [JSON schema docs](https://json-schema.org/understanding-json-schema/reference/) for a full list of references for various types
+Add each exported payload to `examplesToConvert` in `/scripts/build-json-examples` and `examplesToTest` in `/tests/usage.test.ts`.
 
-## Publishing
-To publish a new version, commit a change to `main` which increments `package.json` version. 
+Run `pnpm build-json-examples` to automatically generate a corresponding JSON file per example payload in the root of `/examples`.
+
+Run `pnpm test` to confirm your example payload can be successfully validated against the Digital Planning Data schema.
 
-GitHub actions will then checkout the `dist` branch and commit your change, and they'll be published via GitHub pages at `http://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schema.json`
+## Publishing
+To publish a new version, open a pull request against `main` which increments the `package.json` version.
 
-For more details, take a look at [publish.yml](https://github.com/theopensystemslab/digital-planning-data-schemas/blob/main/.github/workflows/publish.yml)
+On merge, the [publish.yml](https://github.com/theopensystemslab/digital-planning-data-schemas/blob/main/.github/workflows/publish.yml) GitHub Action will update the `dist` branch, create a release, and publish the new version via GitHub pages at `http://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schema.json`
 
 ## Contributing
-We welcome contributions from the community to help us improve and expand our Digital Planning data schemas. Whether you find a bug, want to propose an enhancement, or have created a new schema that you believe would benefit others, we encourage you to get involved by opening an issue.
+We welcome feedback, bug reports, and contributions to help improve and grow the Digital Planning Data schemas via GitHub Issues and Pull Requests.
 
 ## License
 Distributed under the Mozilla Public License Version 2.0. See `LICENSE.txt` for more information.
-
-## Feedback
-If you have any suggestions, questions, or concerns related to our Digital Planning data schemas or the repository itself, please open an Issue on GitHub.