JSON Schema Semantic Versioning

user_12527124 0
Viewed 756

I have a service that manages some system configurations, these configurations are stored in the filesystem as a .json file. On each boot, the service will start, read the configuration and use the values to modify said system configurations.

Before using the values, I'm using a JSON schema validator, to confirm that the data is okay.

Now my question is, how can I achieve semantic versioning for the JSON schema and check if the json data is using the correct version.

Currently if the schema changes and the data doesn't the validator exits with an error code, which is good. But what isn't great is the error message I'm receiving.

What I like to do is, check before validation if the version of the data matches the version of the schema, and if it doesn't, throw an expection that tells the user that the data is incompatible to the schema because of a version mismatch.

After doing some research I came across the following key in the JSON schema:

"$id": "https://my-company.org/schemas/config/0.1.0/config.schema.json"

This URI could be used for controlling the version of the schema itself, but how would i check if the data is using the correct version of that schema?

json-schema-validator jsonschema json
1 Answers

Storing the version identifier as part of the URI in $id is common, and seems to be the best solution for versioning JSON Schema. (I haven't seen a better solution, and it is proven that this approach works at scale.)

Alternativly, you could add your own field in JSON Schema, but people and code would need to know to look for it.

When you validate data with JSON Schema, you sometimes load in all your schemas, then specify the ID of the one you want to use.

Storing the schema version you want some JSON data to be validated against can be done however you like. While not defined in the JSON Schema specification, it's commonplace to store the full URI as defined in the schemas $id value to be inculded in the data in a $schema field.

It's not defined in the specification because we don't want to prescribe requirements on data.

user_892110
Related