PATCH: add $id properties to schema files #419
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
JSON Schema 2020-12 supports the $id property to give schemas a URI which uniquely references them. This commit adds $id properties to the 360Giving Schema and the 360Giving Package Schema. https://json-schema.org/draft/2020-12/json-schema-core.html (Section 8.2.1) The value of each schema's $id is treated as the canonical identifier for the schema. This brings the following benefits to the 360Giving Standard: 1. Each version of the schema can be uniquely identified, allowing us to reliably support multiple versions of the standard simulataneously in tooling. 2. Enables tools to reliably cache the schema by checking whether they have a cached copy with the same $id as the the branch of the schema that they are checking against. This evades the upcoming Github rate limiting issues. 3. Uniquely identifying the schema means that other Standards can reference it in their data models. For example HSDS has a `funding` schema, and it is conceivable that they may want to make it interoperate with 360Giving by referencing the 360Giving Schema. This does NOT affect existing validation or published data. This change does not affect the 360Giving data models at all, only adds a JSON Schema identifier for the schema files which follows best practice and brings the above benefits. See other standards which use $id: * Open Fibre: https://raw.githubusercontent.com/Open-Telecoms-Data/open-fibre-data-standard/0__3__0/schema/network-schema.json * OpenLineage: https://openlineage.io/spec/2-0-2/OpenLineage.json Open Contracting use the "id" property, which was how this was achieved in JSON Schema Draft 04: https://standard.open-contracting.org/schema/1__1__5/release-schema.json (reference: https://json-schema.org/draft-04/draft-zyp-json-schema-04#rfc.section.7.2)
Because PATCHes MAY update the schema, it might be best to use values for $id which match the PATCH number. This ensures that any tooling which caches schemas won't miss out on a PATCH
mariongalley
approved these changes
Oct 13, 2025
Contributor
|
A week has passed since the PATCH was proposed in the forum and by email to the Stewardship Committee, with no objections received, so this PATCH is now considered approved. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
JSON Schema 2020-12 supports the $id property to give schemas a URI which uniquely references them. This commit adds $id properties to the 360Giving Schema and the 360Giving Package Schema.
The value of each schema's $id is treated as the canonical identifier for the schema. This brings the following benefits to the 360Giving Standard:
fundingschema, and it is conceivable that they may want to make it interoperate with 360Giving by referencing the 360Giving Schema.This does NOT affect existing validation or published data. This change does not affect the 360Giving data models at all, only adds a JSON Schema identifier for the schema files which follows best practice and brings the above benefits.
See other standards which use $id:
Open Contracting use the "id" property, which was how this was achieved in JSON Schema Draft 04: