Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Support multiple schema types #203

Merged
merged 6 commits into from
Jul 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .eslintrc.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"extends": "./node_modules/gts/",
"rules": {
"node/no-unpublished-import": ["error", {
"n/no-unpublished-import": ["error", {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Required by gts 5.3.1 - https://github.com/google/gts/releases/tag/v5.3.1

Bug Fixes

deps: replace dependency eslint-plugin-node with eslint-plugin-n (google/gts#865) (efbe3a8)

"allowModules": ["vitest", "jsonschema"]
}]
}
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ jobs:
run: |
VERSION=v${{steps.version_check.outputs.version}} pnpm build
mkdir -p "$GITHUB_WORKSPACE/v${{ steps.version_check.outputs.version }}"
mv schema/* "$GITHUB_WORKSPACE/v${{ steps.version_check.outputs.version }}"
mv schemas/* "$GITHUB_WORKSPACE/v${{ steps.version_check.outputs.version }}"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is the only change needed here!

This has the nice benefit of preserving the old URLs in the format -

https://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schema.json

and generating new URLs in the format -

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


mkdir -p "$GITHUB_WORKSPACE/v${{ steps.version_check.outputs.version }}/types"
mv types/* "$GITHUB_WORKSPACE/v${{ steps.version_check.outputs.version }}/types"
Expand Down
2 changes: 1 addition & 1 deletion .husky/pre-commit
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$branch" != "main" ]; then
pnpm build-json-examples && pnpm build-schema:dev
pnpm build
fi

pnpm check && pnpm fix
Expand Down
18 changes: 8 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ There's two main options for integrating with Digital Planning Data schemas:

1. Reference a hosted schema file directly:

`https://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schema.json`
`https://theopensystemslab.github.io/digital-planning-data-schemas/<VERSION>/schemas/<SCHEMA>.json`

1. Clone this repository and reference the local schema files programmatically in your own code using tools that support JSON Schema validation

For more detailed info on integrating and validating schemas, please refer to the examples and tests in this repo.

## Repository structure

`/examples`: Examples of valid payloads for each application type supported by this specification.
`/examples`: Examples of valid payloads for each application type supported by the specifications encoded in this repository.

`/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.
`/schemas`: The main JSON Schema files. The `main` branch of this repo will reflect the `@next` version, while historic versions are documented and released on the `dist` branch.

`/types`: TypeScript interfaces used to generate the JSON Schema.
`/types`: TypeScript interfaces used to generate the JSON Schemas.

`/tests`: Test suites to ensure that the generated schema and example payloads are valid, accurate, and capable of handling different scenarios.

Expand All @@ -37,19 +37,17 @@ pnpm i
```

## Developing
The JSON Schema is defined using TypeScript interfaces and then generated using the `ts-json-schema-generator` library.
The JSON Schemas are defined using TypeScript interfaces and then generated using the `ts-json-schema-generator` library.

To make changes, update `/types` and then run `pnpm build` to automatically generate the output JSON file under `/schema`.
To make changes, update `/types` and then run `pnpm build` to automatically generate the output JSON file under `/schemas`.

Types should be annotated using JSDocs, which will then be read during schema generation.

Please see the [JSON schema docs](https://json-schema.org/understanding-json-schema/reference/) for a full list of references for various types.

## Adding examples and testing

Add a TypeScript file to `/examples/data` with at least one exported variable representing an example payload definition.

Add each exported payload to `examplesToConvert` in `/scripts/build-json-examples` and `examplesToTest` in `/tests/usage.test.ts`.
Add a TypeScript file to `/examples/<SCHEMA>/data` with at least one exported variable representing an example payload definition.

Run `pnpm build-json-examples` to automatically generate a corresponding JSON file per example payload in the root of `/examples`.

Expand All @@ -58,7 +56,7 @@ Run `pnpm test` to confirm your example payload can be successfully validated ag
## Publishing
To publish a new version, open a pull request against `main` which increments the `package.json` version.

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`
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>/schemas/<SCHEMA>.json`

## Contributing
We welcome feedback, bug reports, and contributions to help improve and grow the Digital Planning Data schemas via GitHub Issues and Pull Requests.
Expand Down
Loading