{"id":22310679,"url":"https://github.com/squer-solutions/poc-json-schema-evolution","last_synced_at":"2025-07-02T21:37:44.127Z","repository":{"id":43296366,"uuid":"457429560","full_name":"squer-solutions/poc-json-schema-evolution","owner":"squer-solutions","description":"Exploring and documenting the evolvability of json-schema using a confluent kafka schema registry.","archived":false,"fork":false,"pushed_at":"2022-03-09T10:09:16.000Z","size":20,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-05T10:11:09.264Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squer-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-09T16:03:55.000Z","updated_at":"2025-02-05T22:44:19.000Z","dependencies_parsed_at":"2022-07-21T13:49:23.712Z","dependency_job_id":null,"html_url":"https://github.com/squer-solutions/poc-json-schema-evolution","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/squer-solutions/poc-json-schema-evolution","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squer-solutions%2Fpoc-json-schema-evolution","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squer-solutions%2Fpoc-json-schema-evolution/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squer-solutions%2Fpoc-json-schema-evolution/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squer-solutions%2Fpoc-json-schema-evolution/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squer-solutions","download_url":"https://codeload.github.com/squer-solutions/poc-json-schema-evolution/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squer-solutions%2Fpoc-json-schema-evolution/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263220994,"owners_count":23432980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T21:14:08.379Z","updated_at":"2025-07-02T21:37:44.072Z","avatar_url":"https://github.com/squer-solutions.png","language":"TypeScript","readme":"# Intro\nThis repo consists of two parts ...\n* test-code exploring the json-schema evolution\n* documentation outlining the findings\n\nTo cut straight to the chase, we first outline the findings and then describe how to set up and run the tests\non your own to do your own experimentation / draw your own conclusions.\n\n# JSON-Schema Evolution\nJSON-Schema is one of the schema types supported by the Confluent Schema Registry. It is not prominently mentioned in the\ndocumentation, leading one to assume that it behaves just like AVRO does. It doesn't. The canonical explanation referenced\nin issues on the Confluent Schema Registry [repository](https://github.com/confluentinc/schema-registry/) is \n[this](https://yokota.blog/2021/03/29/understanding-json-schema-compatibility/).\n\nSince it was not immediately obvious to us how this translates into using json-schema we did some experimentation.\n\n## FORWARD Compatibility\n\u003e Forward compatibility – all documents that conform to the new version are also valid according to the previous version of the schema\n\n| AdditionalProperties | true | false |\n|----------------------|------|-------|\n| Add optional         | :heavy_check_mark: | :x: |\n| Add mandatory        | :heavy_check_mark: | :x: |\n| Remove optional      | :x: | :heavy_check_mark: |\n| Remove mandatory     | :x: | :x: |\n\nForward Compatible topics can **only** transition from `true` -\u003e `false` for `additionalProperties`.\n\n## BACKWARD Compatibility\n\u003e Backward compatibility – all documents that conform to the previous version of the schema are also valid according to the new version.\n\n| AdditionalProperties | true | false |\n|----------------------|------|-------|\n| Add optional         | :x: | :heavy_check_mark: |\n| Add mandatory        | :x: | :x: |\n| Remove optional      | :heavy_check_mark: | :x: |\n| Remove mandatory     | :heavy_check_mark: | :x: |\n\n**WARNING:**\nTransitioning from `additionalProperties=true` to `false` is not possible! \n\n## Rollbacks\nIt should be noted that you can use old versions of schemas! Meaning that rollbacks and rolling updates are possible for\nboth FORWARD and BACKWARD compatible schemas.\n\n## Addendum: What is additionalProperties?\nAs seen above, additionalProperties has a big impact on the compatibility of the kafka models.To not reiterate what has \nalready been said better, you can read up on the open, closed and partially open content models in \njson-schema [here](https://yokota.blog/2021/03/29/understanding-json-schema-compatibility/).\n\nThe most important thing to understand is that, by setting additionalProperties to `true` (the default), we essentially say:\n\"This schema describes the minimum of what my message will contain - but anything else could be part of it as well.\"\n\nThis is why, in FORWARD compatibility, removing an optional field is not possible with `true`. We essentially stop guaranteeing\nthat we will deliver a field, but \"anything else could be part of it as well.\" means that a field with the same name is also\nincluded in what our new schema describes. This is a potential conflict and therefore not allowed.\n\nSimilar reasoning applies to BACKWARD compatibility. We cannot add any fields because all potential other fields are already included\nin \"anything else could be part of it as well.\" - by introducing a new field we'd be asking for a conflict according to json-schema.\n\nThis presents us with severe constraints on BACKWARDS compatibility.\n\n## Final Notes\nPlease feel free to contribute and give feedback - we'd be happy to learn more and/or to get a more complete suite of tests showing\nwhat is an isn't possible.\n\n## Related Issues\n* https://github.com/confluentinc/schema-registry/issues/1458\n* https://github.com/confluentinc/schema-registry/issues/1778\n* https://github.com/confluentinc/schema-registry/issues/2121\n\n# Setup and Running the Tests\n### Getting Started with NodeJS\nTo get started with this repository we assume that you have the following installed locally...\n\n#### Docker Desktop\nFollow this link for instructions: https://docs.docker.com/get-docker/\n\n#### Node Version Manager\nYou will need Node on your machine to be able to run the application. We will use the Node Version Manager to install\nour first node install. Follow the official install guide for NVM: https://github.com/nvm-sh/nvm. \nAfterwards, navigate to the root directory of the repository and ...\n```shell\nnvm use\n```\n... you might need to install the requested version. Follow the feedback the tool gives you.\n\nTo pull all the dependencies needed, run...\n```shell\nnpm install\n```\n.. you should be ready to run the code in this repository.\n\n### Running the Tests\nTo execute the exploratory tests, run...\n```shell\nnpm run test\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquer-solutions%2Fpoc-json-schema-evolution","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquer-solutions%2Fpoc-json-schema-evolution","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquer-solutions%2Fpoc-json-schema-evolution/lists"}