Install & Compatibility
Where this runs
tested against v0.12.0 · 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.960 runs
installs and imports cleanly · install 0.0s · import 0.228s · 18.3MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 1.6s · import 0.218s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load
✓ from jsonspec.validators import load
json_pointer
✓ import jsonspec.pointer as json_pointer
Common alias for JSON Pointer operations
json_reference
✓ import jsonspec.reference as json_reference
Common alias for JSON Reference operations
This quickstart demonstrates how to define a JSON Schema, create a validator using `jsonspec.validators.load`, and validate JSON instances against it. It also includes a basic example of using JSON Pointer to extract a value from a JSON document. The `load` function defaults to JSON Schema Draft 04, but can be explicitly set to Draft 03 if needed.
from jsonspec.validators import load
from jsonspec.pointer import Pointer
# Define a JSON Schema (defaults to Draft 04)
schema = {
'title': 'Example Schema',
'type': 'object',
'properties': {
'name': {'type': 'string'},
'age': {'type': 'integer', 'minimum': 0}
},
'required': ['name', 'age']
}
# Compile the schema into a validator
validator = load(schema)
# Instance to validate
valid_instance = {'name': 'Alice', 'age': 30}
invalid_instance = {'name': 'Bob', 'age': -5}
missing_field_instance = {'name': 'Charlie'}
# Perform validation
try:
validator.validate(valid_instance)
print("Valid instance is valid.")
except Exception as e:
print(f"Valid instance failed validation: {e}")
try:
validator.validate(invalid_instance)
print("Invalid instance (negative age) is valid.")
except Exception as e:
print(f"Invalid instance (negative age) failed validation: {e}")
try:
validator.validate(missing_field_instance)
print("Invalid instance (missing field) is valid.")
except Exception as e:
print(f"Invalid instance (missing field) failed validation: {e}")
# Example of JSON Pointer (requires explicit import/use)
data_for_pointer = {'foo': ['bar', 'baz', {'qux': 10}]}
pointer = Pointer('/foo/2/qux')
value = pointer.get(data_for_pointer)
print(f"Value at /foo/2/qux: {value}")
Debug
Known issues
breakingThe `json-spec` library primarily supports JSON Schema Draft 03 and Draft 04. This is a critical limitation as the JSON Schema specification has evolved significantly, with Draft 2020-12 being the latest standard. Users requiring features from newer drafts (e.g., Draft 07, 2019-09, 2020-12) will find this library insufficient or experience unexpected behavior.fixFor newer JSON Schema drafts, consider using the more actively maintained `jsonschema` library (pypi: `jsonschema`) which supports Draft 2020-12 and earlier modern drafts. If locked to older schemas, ensure your schemas conform to Draft 03 or Draft 04 specifications.
affects: All versions of `json-spec` (including 0.12.0) that adhere to its stated Draft 03/04 support.
gotchaCommon JSON syntax errors (e.g., trailing commas, unquoted object keys, single quotes instead of double quotes for strings, comments within JSON) will result in parsing failures. While not specific to `json-spec`, these are frequent mistakes when authoring JSON schemas or instances.fixEnsure all JSON data (schemas and instances) strictly adhere to the JSON specification. Use linters, validators (like `json.tool` in Python's standard library), or IDE extensions to catch these errors early.
affects: All versions of `json-spec` (and generally any JSON parser).
gotchaThe JSON Schema specification itself sometimes leaves certain behaviors 'undefined' leading to 'indeterminate' validation results. Different implementations of JSON Schema might resolve these ambiguities in varying ways, potentially leading to inconsistent validation outcomes across different tools or libraries.fixBe aware of potential ambiguities when designing complex schemas. Test your schemas with multiple JSON Schema validators if cross-platform or cross-implementation consistency is critical. Refer to the official JSON Schema specification for details on defined vs. undefined behaviors.
affects: All versions, as this is a characteristic of the JSON Schema specification itself.
Errors
Common errors & fixes
jsonspec.validators.ValidationError: ...
The provided JSON instance does not conform to the structure or constraints defined by the JSON schema.
fixReview the detailed error message for specific violations (e.g., incorrect data type, missing required property, value out of range) and modify the JSON instance to align with the schema's requirements.
jsonspec.validators.SchemaError: ...
The JSON schema itself is invalid, often due to using keywords or constructs that are not supported by JSON Schema Draft 03 or Draft 04, which are the versions 'json-spec' implements. For example, using a Draft 07 'if/then/else' keyword would cause this error.
fixModify the JSON schema to adhere strictly to the JSON Schema Draft 03 or Draft 04 specifications. Remove or replace any keywords or patterns that were introduced in later drafts.
ModuleNotFoundError: No module named 'jsonspec'
The 'json-spec' library is either not installed in your Python environment or the import statement is attempting to import from an incorrect top-level module name.
fixInstall the library using `pip install json-spec`. Ensure your import statements are correct, typically `from jsonspec.validators import load` or other specific submodules like `jsonspec.pointer` or `jsonspec.reference`.
Upgrade
Version history
0.12.0latest on PyPI · released Apr 29, 2024
Audit
Dependencies
jsonschemaoptionalThis library implements *some* JSON specs, but the more popular `jsonschema` library often handles more modern JSON Schema drafts. Users might confuse them or need both.