Introducing versioning in JSON schema validation

We’re excited to announce some significant changes to the JSON schema validation in KrakenD. These updates are aimed at improving versioning and organization, providing clearer support for different KrakenD versions, and enabling broader usage of JSON schemas beyond just configuration files. Let’s delve into the details of these changes.

From a unique schema to one schema per version

Previously to writing this post, we had a single schema validation URL (https://www.krakend.io/schema/v3.json) that applied to all KrakenD configurations starting with version: 3, which has been the case since March 2022 and we have kept releasing a lot of times since then. However, this approach could have been better for users falling behind and not updating their configurations frequently, as the validator would tell you that a configuration is valid, but your older KrakenD version would not recognize the newly introduced feature.

We have decided to introduce KrakenD versioning in the schema to address this situation. For example, the new schema for version 2.3 will be available at https://www.krakend.io/schema/v2.3/krakend.json. Each KrakenD version will have moving forward its schema available.

Following semantic versioning (versions tagged as Major.Minor.Patch), there won’t be specific schemas for patches (e.g., 2.3.1) as patches do not change the configuration behavior.

From v3.json to krakend.json

As part of this update, we have also renamed the latest version of the JSON schema to krakend.json (previously v3.json). The purpose of this change is to accommodate other validations beyond KrakenD configuration files (for instance, integration test validation). By expanding the scope of the schema, we aim to provide a more comprehensive validation framework for various use cases.

Schema embedded in a future version

The krakend check --lint option downloads the v3.json file today, no matter its version. In future releases, each version will use its specific schema, and we will also provide an option to validate it offline without Internet Access.

What should I do?

To ensure backward compatibility and keep linters working smoothly, we will continue to support the URL v3.json till the end of time. Well, not really, but for now if you don’t change anything, it will keep working as it was.

However, we recommend you to replace any line of https://www.krakend.io/schema/v3.json with https://www.krakend.io/schema/v2.3/krakend.json, so when we update to v2.4 new features won’t be suggested and mistakenly validated in your configuration.

Documentation updated

Regarding documentation, we have made appropriate adjustments to reflect these changes. The old version’s documentation will point now to their respective old schemas, ensuring that users can access the correct information based on the KrakenD version they are using.

Conclusions

These updates are part of our ongoing efforts to enhance the KrakenD ecosystem and provide a more streamlined and accurate validation experience. These changes will benefit new and existing KrakenD users by reducing confusion and ensuring compatibility. Adopting and deprecating new features will now be more straightforward, more precise, and safer.

Please explore the updated JSON schema validation in KrakenD and provide feedback. Your input is invaluable in shaping the future development of KrakenD.

Thank you for your continued support, and happy schema validating!