JSON Spec

Warnings

• breaking The `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.
  Fix: For 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.
• gotcha Common 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.
  Fix: Ensure 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.
• gotcha The 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.
  Fix: Be 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.

Install

• pip install json-spec Core library
• pip install json-spec[cli] With CLI tools (e.g., colorated messages)
• pip install json-spec[ip] With IP format validation for JSON Schema

Imports

• 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

Quickstart

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}")