JSON Schema Compatibility Checker

0.3.1 · active · verified Thu Apr 09

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.

Warnings

gotcha 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.
Fix: Exercise caution and consider using additional validation methods for critical systems. Monitor the project's development for stability updates.
gotcha 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.
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).
gotcha 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.
Fix: Always convert Python dictionaries representing schemas to JSON strings using `json.dumps()` before passing them to `jsoncompat` functions.
gotcha Functions like `check_compat` and `generate_value` will raise a `ValueError` for invalid schemas or unsupported compatibility features (e.g., unsatisfiable schemas).
Fix: Implement robust `try-except ValueError` blocks around calls to `jsoncompat` functions to gracefully handle and log schema-related issues.

Install

pip install jsoncompat Install latest version

Imports

jsoncompat
```
import jsoncompat as jsc
```
The common convention is to import it as `jsc` for brevity.
check_compat
```
jsc.check_compat(old_schema_json, new_schema_json, role)
```
Schemas must be passed as JSON strings, not Python dictionaries.
generate_value
```
jsc.generate_value(schema_json)
```
Schemas must be passed as JSON strings, not Python dictionaries.

Quickstart

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.

import jsoncompat as jsc
import os

# Define old and new schemas as JSON strings
old_schema = '{"type": "string"}'
new_schema = '{"type": "number"}'

# Check compatibility (role: "serializer", "deserializer", or "both")
# Raises ValueError for invalid schemas or unsupported compatibility features.
try:
    is_compatible = jsc.check_compat(old_schema, new_schema, role="both")
    print(f"Schemas compatible (both roles): {is_compatible}")

    # Example of generating a value from a schema
    schema_with_enum = '{"type": "string", "enum": ["foo", "bar"]}'
    generated_value = jsc.generate_value(schema_with_enum)
    print(f"Generated value for schema: {generated_value}")

except ValueError as e:
    print(f"An error occurred: {e}")

view raw JSON →