Install & Compatibility
Where this runs
tested against v0.7.8 · 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.034s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.030s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
This quickstart defines a schema for a list of personal information entries, including validation for name length, age range (with type conversion), and an optional gender field with specific allowed values. It then attempts to validate both valid and invalid data, demonstrating how `Schema.validate()` works and how `SchemaError` is raised for invalid input.
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}")
Debug
Known issues
gotchaDo 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.fixEnsure you are importing from the correct library based on whether you need a Pythonic schema definition or adherence to the JSON Schema specification.
affects: All versions
gotchaSince 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.fixWhen 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.
affects: 0.6.2 and later
deprecatedThe `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.fixAlways use `schema` with a currently supported Python version (e.g., Python 3.8+). Update your Python environment if necessary.
affects: < 0.7.0 (for explicit Python 2/older 3 support), all versions when used with EOL Python runtimes
gotchaAn 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.fixEnsure 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.
affects: Potentially a specific, short-lived version prior to 0.6.4
Errors
Common errors & fixes
ImportError: cannot import name 'Base' from 'schema'
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.
fixRename the local 'schema.py' file to avoid conflicts with the 'schema' library.
ModuleNotFoundError: No module named 'schema'
This error occurs when the 'schema' library is not installed in the Python environment.
fixInstall the 'schema' library using pip: 'pip install schema'.
schema.SchemaError: '123' should be instance of 'int'
This error occurs when the data being validated does not match the expected type defined in the schema.
fixEnsure that the data being validated matches the expected type; for example, convert strings to integers before validation.
schema.SchemaError: exists('./non-existent/') should evaluate to True
This error occurs when a validation function, such as 'os.path.exists', returns False for the provided data.
fixVerify that the data being validated meets the conditions of the validation function; for example, check that the file or directory exists.
schema.SchemaError: Missing keys: 'some_key'
The input data is missing one or more keys that are defined as required in the schema.
fixEnsure 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.
Upgrade
Version history
0.7.8latest on PyPI · released Oct 11, 2025
Audit
Dependencies
No dependency data recorded yet.