Install & Compatibility
Where this runs
tested against v0.1.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.010s · 18MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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)
✗ jsc.check_compat(old_schema_dict, new_schema_dict, role)
Schemas must be passed as JSON strings, not Python dictionaries.
generate_value
✓ jsc.generate_value(schema_json)
✗ jsc.generate_value(schema_dict)
Schemas must be passed as JSON strings, not Python dictionaries.
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}")
Debug
Known issues
gotchaThe 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.fixExercise caution and consider using additional validation methods for critical systems. Monitor the project's development for stability updates.
affects: All versions up to 0.3.1
gotchaThe `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.fixCarefully 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).
affects: All versions up to 0.3.1
gotchaSchemas 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.fixAlways convert Python dictionaries representing schemas to JSON strings using `json.dumps()` before passing them to `jsoncompat` functions.
affects: All versions up to 0.3.1
gotchaFunctions like `check_compat` and `generate_value` will raise a `ValueError` for invalid schemas or unsupported compatibility features (e.g., unsatisfiable schemas).fixImplement robust `try-except ValueError` blocks around calls to `jsoncompat` functions to gracefully handle and log schema-related issues.
affects: All versions up to 0.3.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsoncompat'
The 'jsoncompat' Python package is not installed in the current environment or the Python interpreter cannot find it.
fixInstall the package using pip: `pip install jsoncompat`
TypeError: 'schema' argument must be a string or dict, not <type>
A function within the `jsoncompat` library received an argument of an incorrect Python type for a schema (e.g., an integer instead of a JSON string or dictionary).
fixEnsure that JSON schema arguments passed to `jsoncompat` functions are correctly formatted as Python strings (containing JSON) or Python dictionaries.
ValueError: Invalid JSON schema: <specific_reason>
The input provided to a `jsoncompat` function, while potentially syntactically valid JSON, does not conform to a valid JSON Schema specification (e.g., missing required keywords, incorrect keyword values).
fixReview and correct your JSON schema against the JSON Schema specification. Use a JSON Schema linter or validator to pre-check your schema for structural and semantic correctness.
Compatibility check failed: <specific_incompatibility_details>
When using `jsoncompat.check_compatibility()` or the `jsoncompat compat` CLI, the library detected that the provided schemas are incompatible (e.g., a backward-incompatible change was introduced).
fixAnalyze the detailed output from `jsoncompat` to understand the specific breaking change. Modify one or both schemas to resolve the incompatibility, or adjust your development process if the breaking change is intentional.
Upgrade
Version history
0.4.2latest on PyPI · released Aug 5, 2026
Audit
Dependencies
No dependency data recorded yet.