{"id":2084,"library":"jsoncompat","title":"JSON Schema Compatibility Checker","description":"jsoncompat provides Python bindings for a Rust core, enabling robust checking of compatibility between evolving JSON schemas and automatic generation of representative sample data. It helps developers ensure backward and forward compatibility for APIs and data storage, preventing unintended breaking changes. The current version is 0.3.1, and it maintains an active release cadence.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/ostrowr/jsoncompat","tags":["JSON","schema","validation","compatibility","API","data-modeling"],"install":[{"cmd":"pip install jsoncompat","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The common convention is to import it as `jsc` for brevity.","symbol":"jsoncompat","correct":"import jsoncompat as jsc"},{"note":"Schemas must be passed as JSON strings, not Python dictionaries.","wrong":"jsc.check_compat(old_schema_dict, new_schema_dict, role)","symbol":"check_compat","correct":"jsc.check_compat(old_schema_json, new_schema_json, role)"},{"note":"Schemas must be passed as JSON strings, not Python dictionaries.","wrong":"jsc.generate_value(schema_dict)","symbol":"generate_value","correct":"jsc.generate_value(schema_json)"}],"quickstart":{"code":"import jsoncompat as jsc\nimport os\n\n# Define old and new schemas as JSON strings\nold_schema = '{\"type\": \"string\"}'\nnew_schema = '{\"type\": \"number\"}'\n\n# Check compatibility (role: \"serializer\", \"deserializer\", or \"both\")\n# Raises ValueError for invalid schemas or unsupported compatibility features.\ntry:\n    is_compatible = jsc.check_compat(old_schema, new_schema, role=\"both\")\n    print(f\"Schemas compatible (both roles): {is_compatible}\")\n\n    # Example of generating a value from a schema\n    schema_with_enum = '{\"type\": \"string\", \"enum\": [\"foo\", \"bar\"]}'\n    generated_value = jsc.generate_value(schema_with_enum)\n    print(f\"Generated value for schema: {generated_value}\")\n\nexcept ValueError as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to use `jsoncompat` to check the compatibility between two JSON schemas and generate a sample value from a given schema. Schemas are provided as JSON strings, and the `check_compat` function requires a 'role' parameter to specify the direction of compatibility checking."},"warnings":[{"fix":"Exercise caution and consider using additional validation methods for critical systems. Monitor the project's development for stability updates.","message":"The library is explicitly stated as 'alpha software'. This means not all incompatible changes may be detected, and there could be false positives. Users should be aware of its experimental nature.","severity":"gotcha","affected_versions":"All versions up to 0.3.1"},{"fix":"Carefully review the documentation for the 'role' parameter and its impact on compatibility logic. Choose the role that accurately reflects how your schemas are being used (e.g., API request vs. response, data storage).","message":"The `role` parameter in `check_compat` (must be 'serializer', 'deserializer', or 'both') is crucial. Misunderstanding the implications of schema changes for different roles (e.g., adding a required property is breaking for a deserializer but not necessarily for a serializer) can lead to incorrect compatibility assessments.","severity":"gotcha","affected_versions":"All versions up to 0.3.1"},{"fix":"Always convert Python dictionaries representing schemas to JSON strings using `json.dumps()` before passing them to `jsoncompat` functions.","message":"Schemas must be provided as raw JSON *strings* (e.g., `'{\"type\": \"string\"}'`), not Python dictionary objects. This differs from some other popular JSON schema libraries in Python (like `jsonschema`) and is a common source of `ValueError` exceptions.","severity":"gotcha","affected_versions":"All versions up to 0.3.1"},{"fix":"Implement robust `try-except ValueError` blocks around calls to `jsoncompat` functions to gracefully handle and log schema-related issues.","message":"Functions like `check_compat` and `generate_value` will raise a `ValueError` for invalid schemas or unsupported compatibility features (e.g., unsatisfiable schemas).","severity":"gotcha","affected_versions":"All versions up to 0.3.1"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}