Schema
raw JSON → 0.7.8 verified Tue May 12 auth: no python install: verified
Schema is a Python library for validating data structures, such as those obtained from config files, forms, external services, or command-line parsing, often converted from JSON/YAML to Python data types. It is actively maintained with moderate release frequency, typically addressing bug fixes and minor features, with occasional larger updates.
pip install schema Common errors
error ImportError: cannot import name 'Base' from 'schema' ↓
cause This error occurs when there's a naming conflict between a local module named 'schema' and the installed 'schema' library, leading Python to import the local module instead.
fix
Rename the local 'schema.py' file to avoid conflicts with the 'schema' library.
error ModuleNotFoundError: No module named 'schema' ↓
cause This error occurs when the 'schema' library is not installed in the Python environment.
fix
Install the 'schema' library using pip: 'pip install schema'.
error schema.SchemaError: '123' should be instance of 'int' ↓
cause This error occurs when the data being validated does not match the expected type defined in the schema.
fix
Ensure that the data being validated matches the expected type; for example, convert strings to integers before validation.
error schema.SchemaError: exists('./non-existent/') should evaluate to True ↓
cause This error occurs when a validation function, such as 'os.path.exists', returns False for the provided data.
fix
Verify that the data being validated meets the conditions of the validation function; for example, check that the file or directory exists.
error schema.SchemaError: Missing keys: 'some_key' ↓
cause The input data is missing one or more keys that are defined as required in the schema.
fix
Ensure the input data dictionary contains all keys specified as required in the schema, or mark keys as
Optional in the schema definition if they are not always present. Warnings
gotcha Do not confuse `schema` (keleshev/schema) with `jsonschema`. This library provides a Pythonic way to define and validate data structures, and can generate JSON schema from its definitions. `jsonschema` is a separate library that strictly implements the JSON Schema specification. ↓
fix Ensure you are importing from the correct library based on whether you need a Pythonic schema definition or adherence to the JSON Schema specification.
gotcha Since version 0.6.2, `schema.SchemaError` has specific subclasses like `SchemaWrongKey` and `SchemaMissingKeyError`. While `except SchemaError` will still catch these, code that relies on precise error type checking for key-related issues (e.g., `isinstance(e, SchemaWrongKey)`) may need to be updated if it was written before these subclasses were introduced and expected only the base `SchemaError` class for specific key problems. ↓
fix When catching `SchemaError`, consider if more granular handling is needed for `SchemaWrongKey`, `SchemaMissingKeyError`, or other specific subclasses. Generally, catching the base `SchemaError` is sufficient for overall validation failure.
deprecated The `schema` library was tested against older Python versions (e.g., Python 2.6, 2.7, 3.2-3.9). These older Python versions are no longer officially supported by the Python Software Foundation and may have security vulnerabilities or compatibility issues with modern libraries. ↓
fix Always use `schema` with a currently supported Python version (e.g., Python 3.8+). Update your Python environment if necessary.
gotcha An issue related to `Optional` fields was reverted in version 0.6.4 ("Revert the optional error commit"). This implies a temporary instability or unexpected behavior regarding `Optional` field validation in an intermediate version prior to 0.6.4. Users upgrading from a version that contained this problematic change might have encountered validation issues. ↓
fix Ensure you are using version 0.6.4 or later if you experienced unexpected behavior with `Optional` fields in older installations. Always test `Optional` field behavior thoroughly after any major version upgrade.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.02s 17.9M
3.10 alpine (musl) - - 0.02s 17.9M
3.10 slim (glibc) wheel 1.4s 0.02s 18M
3.10 slim (glibc) - - 0.01s 18M
3.11 alpine (musl) wheel - 0.04s 19.7M
3.11 alpine (musl) - - 0.05s 19.7M
3.11 slim (glibc) wheel 1.5s 0.04s 20M
3.11 slim (glibc) - - 0.03s 20M
3.12 alpine (musl) wheel - 0.04s 11.6M
3.12 alpine (musl) - - 0.05s 11.6M
3.12 slim (glibc) wheel 1.5s 0.04s 12M
3.12 slim (glibc) - - 0.04s 12M
3.13 alpine (musl) wheel - 0.04s 11.3M
3.13 alpine (musl) - - 0.04s 11.2M
3.13 slim (glibc) wheel 1.4s 0.04s 12M
3.13 slim (glibc) - - 0.04s 12M
3.9 alpine (musl) wheel - 0.02s 17.4M
3.9 alpine (musl) - - 0.02s 17.4M
3.9 slim (glibc) wheel 1.7s 0.02s 18M
3.9 slim (glibc) - - 0.01s 18M
Imports
- Schema
from schema import Schema - And
from schema import And - Or
from schema import Or - Use
from schema import Use - Optional
from schema import Optional - Regex
from schema import Regex - SchemaError
from schema import SchemaError
Quickstart last tested: 2026-04-24
from schema import Schema, And, Use, Optional, SchemaError
schema = Schema(
[
{
"name": And(str, len),
"age": And(Use(int), lambda n: 18 <= n <= 99),
Optional("gender"): And(str, Use(str.lower), lambda s: s in ("male", "female", "other")),
}
]
)
data = [
{"name": "Sue", "age": "28", "gender": "Female"},
{"name": "Sam", "age": "42"},
{"name": "Sacha", "age": "20", "gender": "Other"},
]
try:
validated_data = schema.validate(data)
print("Validation successful!")
print(validated_data)
except SchemaError as e:
print(f"Validation failed: {e}")
# Example of invalid data
invalid_data = [
{"name": "Alice", "age": "15"} # Age too young
]
try:
schema.validate(invalid_data)
except SchemaError as e:
print(f"Validation failed for invalid data: {e}")