Of course! validictory is a popular, lightweight Python library for validating data structures against a JSON Schema. It's known for its simplicity and speed.

Here's a comprehensive guide covering what it is, how to install it, and how to use it with detailed examples.

What is validictory?

validictory is a Python library that lets you validate a Python data structure (like a dictionary or a list) against a JSON Schema.

JSON Schema is a JSON-based format for describing the structure of JSON data. It acts as a "blueprint" or a "contract" for your data, defining what fields are required, their data types, formats, and any constraints (e.g., minimum/maximum values).

validictory's main strengths are:

• Simplicity: The API is very straightforward.
• Performance: It's written in pure Python and is generally faster than some of its heavier counterparts.
• Standard Compliance: It supports a good portion of the JSON Schema specification.

Installation

You can install validictory easily using pip:

pip install validictory

Basic Concepts

Before diving into code, let's understand the core components:

• Data to Validate: This is your Python object. Usually, it's a dictionary or a list.

  user_data = {
      "name": "Alice",
      "age": 30,
      "email": "alice@example.com",
      "is_active": True
  }

• Schema: This is the "rulebook" for your data. It's a Python dictionary that mirrors the JSON Schema format. It defines the expected structure and constraints.

  user_schema = {
      "type": "object",
      "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "email": {"type": "string"},
          "is_active": {"type": "boolean"}
      },
      "required": ["name", "age", "email"]
  }

• Validation: You pass the data and the schema to the validate() function. If the data conforms to the schema, the function does nothing. If it doesn't, it raises a validictory.ValidationError with a descriptive message.

Core Usage and Examples

Let's start with a simple example and build up to more complex schemas.

Example 1: Basic Validation

This example validates a simple user object.

import validictory
# The data we want to validate
user_data = {
    "name": "Bob",
    "age": 25,
    "email": "bob@example.com",
    "is_active": True
}
# The schema defining the rules for the data
user_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "email": {"type": "string"},
        "is_active": {"type": "boolean"}
    },
    "required": ["name", "age", "email"] # These fields must be present
}
try:
    validictory.validate(user_data, user_schema)
    print("Validation successful!")
except validictory.ValidationError as e:
    print(f"Validation failed: {e}")
# --- Expected Output ---
# Validation successful!

Example 2: Validation Failure

Now, let's see what happens when the data doesn't match the schema.

import validictory
# This data is missing the 'email' field and has a wrong type for 'age'
invalid_user_data = {
    "name": "Charlie",
    "age": "thirty", # Should be an integer
    # "email": "charlie@example.com" # Missing required field
}
user_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "email": {"type": "string"}
    },
    "required": ["name", "age", "email"]
}
try:
    validictory.validate(invalid_user_data, user_schema)
    print("Validation successful!")
except validictory.ValidationError as e:
    print(f"Validation failed: {e}")
# --- Expected Output ---
# Validation failed: data['age'] is not an integer (got 'thirty')
# Note: It reports the first error it finds. The missing 'email' error is not shown.

Advanced Schema Features

validictory supports many features of the JSON Schema specification.

A. Data Types

You can enforce types for fields.

schema = {
    "type": "object",
    "properties": {
        "username": {"type": "string"},
        "score": {"type": "number"}, # For both int and float
        "is_premium": {"type": "boolean"},
        "tags": {"type": "array"},
        "profile": {"type": "object"}
    }
}
data = {
    "username": "diana",
    "score": 99.5,
    "is_premium": False,
    "tags": ["warrior", "amazon"],
    "profile": {}
}
validictory.validate(data, schema)

B. String Constraints

You can add rules for strings, like minimum length or a specific format (e.g., for an email or URL).

import validictory
email_schema = {
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "format": "email" # Checks for a basic email pattern
        },
        "password": {
            "type": "string",
            "minLength": 8
        }
    }
}
valid_email_data = {"email": "eve@example.com", "password": "verysecure123"}
invalid_email_data = {"email": "not-an-email", "password": "short"}
# Valid case
validictory.validate(valid_email_data, email_schema)
print("Valid email data passed.")
# Invalid case
try:
    validictory.validate(invalid_email_data, email_schema)
except validictory.ValidationError as e:
    print(f"Invalid email data failed: {e}")

Note: The format keyword in validictory is a basic regex check. For more robust validation (e.g., checking if an email domain actually exists), you'd need a separate library.

C. Numeric Constraints

You can set minimum and maximum values for numbers.

product_schema = {
    "type": "object",
    "properties": {
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": True # Price must be > 0
        },
        "quantity": {
            "type": "integer",
            "minimum": 1
        }
    }
}
valid_product = {"price": 19.99, "quantity": 10}
invalid_product_price = {"price": 0, "quantity": 10} # Price is not > 0
validictory.validate(valid_product, product_schema)
print("Valid product passed.")
try:
    validictory.validate(invalid_product_price, product_schema)
except validictory.ValidationError as e:
    print(f"Invalid product failed: {e}")

D. Array Constraints

You can control the items in an array.

schema = {
    "type": "object",
    "properties": {
        "user_ids": {
            "type": "array",
            "items": {"type": "integer"}, # Every item must be an integer
            "minItems": 1,
            "maxItems": 5
        }
    }
}
valid_data = {"user_ids": [101, 102, 103]}
invalid_data = {"user_ids": []} # Fails minItems
validictory.validate(valid_data, schema)
print("Valid array passed.")
try:
    validictory.validate(invalid_data, schema)
except validictory.ValidationError as e:
    print(f"Invalid array failed: {e}")

E. Conditional Logic (if/then/else)

This is a powerful feature from JSON Schema Draft 7. It allows you to apply validation rules conditionally.

# A schema for a user that can be either a 'guest' or a 'member'
conditional_schema = {
    "type": "object",
    "properties": {
        "user_type": {"type": "string", "enum": ["guest", "member"]},
        "member_id": {"type": "integer"}
    },
    # If the user_type is 'member', then member_id is required
    "if": {
        "properties": { "user_type": { "const": "member" } }
    },
    "then": {
        "required": ["member_id"]
    },
    # If the user_type is 'guest', then member_id must NOT be present
    "else": {
        "not": { "required": ["member_id"] }
    }
}
# This should pass
valid_member_data = {"user_type": "member", "member_id": 12345}
validictory.validate(valid_member_data, conditional_schema)
print("Valid member data passed.")
# This should pass
valid_guest_data = {"user_type": "guest"}
validictory.validate(valid_guest_data, conditional_schema)
print("Valid guest data passed.")
# This should fail (member is missing member_id)
invalid_member_data = {"user_type": "member"}
try:
    validictory.validate(invalid_member_data, conditional_schema)
except validictory.ValidationError as e:
    print(f"Invalid member data failed: {e}")
# This should fail (guest has a member_id)
invalid_guest_data = {"user_type": "guest", "member_id": 123}
try:
    validictory.validate(invalid_guest_data, conditional_schema)
except validictory.ValidationError as e:
    print(f"Invalid guest data failed: {e}")

When to Use validictory

• APIs: Perfect for validating incoming request payloads (JSON) against a defined schema.
• Configuration Files: Ensure your application's configuration files are structured correctly.
• Data Import/Export: Validate data before importing it into a database or before exporting it to ensure consistency.
• Simple to Medium Complexity Schemas: It's an excellent choice when you need robust validation without the overhead of a more complex library.

Alternatives to validictory

While validictory is great, other libraries serve similar purposes:

• jsonschema: This is the de-facto standard for JSON Schema validation in Python. It's more comprehensive, supports the latest JSON Schema drafts, and is highly extensible. If you need the most robust and standard-compliant solution, this is the one to choose.
• pydantic: A modern library that goes beyond simple validation. It uses type hints to define data models and automatically performs validation, parsing, and serialization. It's extremely popular in the FastAPI ecosystem and is great for building data-driven applications.
• marshmallow: A very popular library for object serialization/deserialization and validation. It's more feature-rich than validictory but has a slightly different, more imperative style of defining schemas.

Summary

For many projects, validictory provides an excellent balance of simplicity and power. If you find you need more advanced features or want to stick strictly to the latest JSON specification, jsonschema is the logical next step.