Install & Compatibility
Where this runs
tested against v8.10.20260825112551 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.032s · 56.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.1s · import 0.027s · 62MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
schema_salad
✓ import schema_salad
Main module for general use.
load_and_validate
✓ from schema_salad.schema import load_and_validate
✗ from schema_salad import load_and_validate
Specific functions and classes are located in submodules like `schema_salad.schema`, `schema_salad.ref_resolver`, etc.
Fetcher
✓ from schema_salad.fetcher import Fetcher
For custom URI resolution and fetching.
This quickstart demonstrates how to load and validate a SALAD schema and then use that schema to validate a data document. It creates temporary YAML files for the schema and document content, then uses `schema_salad.schema.load_and_validate` and `schema_salad.ref_resolver.Loader` to perform the validation.
import os
import json
from schema_salad.schema import load_and_validate
from schema_salad.ref_resolver import Loader
# Define a simple SALAD schema (YAML string)
schema_content = """
$schema: http://json-schema.org/draft-07/schema#
$id: https://example.com/myschema.yml
type: record
name: MyRecord
documentRoot: true
fields:
- name: id
type: string
jsonldPredicate: '@id'
- name: message
type: string
- name: count
type: int
"""
# Define a document to validate (YAML string)
document_content = """
id: 'my_first_doc'
message: "Hello, SALAD!"
count: 42
"""
# Save schema and document to temporary files
schema_file = 'temp_schema.yml'
document_file = 'temp_document.yml'
with open(schema_file, 'w') as f:
f.write(schema_content)
with open(document_file, 'w') as f:
f.write(document_content)
# Create a Loader instance
loader = Loader({})
# Load and validate the schema itself
print(f"Validating schema: {schema_file}")
schema_salad_obj, _, _ = load_and_validate(schema_file, loader)
print("Schema is valid.")
# Load and validate the document against the schema
print(f"Validating document: {document_file}")
try:
validated_doc, _ = load_and_validate(schema_file, document_file, loader)
print("Document is valid.")
print("Validated document (as Python object):")
print(json.dumps(validated_doc, indent=2))
except Exception as e:
print(f"Document validation failed: {e}")
# Clean up temporary files
os.remove(schema_file)
os.remove(document_file)
schema-salad-tool --version
Debug
Known issues
breakingSchema Salad requires Python 3.10 or newer. Installing or running on older Python versions will result in compatibility errors.fixUpgrade your Python environment to 3.10 or a later supported version.
affects: <=8.9.x (all versions requiring Python 3.10+)
gotchaThe default recursive validation (e.g., via `schema-salad-tool` or direct API calls) preserves line numbers and provides human-readable errors but can be significantly slower for large and deeply nested documents. For performance-critical applications, consider using code generation features, although this may currently result in less descriptive error messages and potential loss of some metadata.fixFor faster validation, investigate `schema-salad-tool --codegen` for your target language. Be aware of the current limitations regarding error messages and information preservation, which are actively being improved.
affects: All versions. Performance trade-offs are inherent to the validation methods.
gotchaUnderstanding the difference between `$import` and `$mixin` directives in SALAD schemas is crucial. `$import` loads an external document without inheriting the context of the importing document, using the imported document's URI as its base. `$mixin` loads a document that *does* inherit the context of the importing document. Misapplying these can lead to incorrect URI resolution, type lookup, and validation behavior.fixCarefully review the SALAD specification regarding `$import` and `$mixin` semantics. Ensure your schema design correctly leverages context inheritance as needed for URI and type resolution.
affects: All versions.
gotchaWhen evolving SALAD schemas, changes to existing fields (e.g., renaming, removing, changing data types, or modifying nullability) can introduce breaking changes for consumers of your documents. Treat your schemas as APIs. It's generally safer to add new fields (additive-only pattern) and deprecate old ones over time, rather than modifying or removing existing fields directly.fixImplement a schema evolution strategy that prioritizes backward compatibility. Communicate schema changes clearly and provide deprecation periods for breaking changes. Avoid silent changes to field names, types, or constraints.
affects: All versions (general schema design principle).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'schema_salad'
The `schema-salad` Python package has not been installed in the current environment or is not available in the Python path.
fixpip install schema-salad
schema_salad.exceptions.SchemaSaladException: Error loading schema
The specified schema file or URL could not be accessed, found, or parsed due to issues like an incorrect path, file permissions, network problems, or malformed YAML/JSON syntax within the schema definition.
fixVerify the schema path/URL is correct and accessible, ensure the file exists and has read permissions, and check the schema's content for syntax errors.
schema_salad.exceptions.ValidationException: value is not a valid
The input document does not conform to the rules defined in the loaded schema, specifically a value failing a type check (e.g., expecting an int but receiving a string) or another schema constraint.
fixAdjust the input document to match the schema's requirements, ensuring all fields have correct types and comply with defined patterns or constraints.
TypeError: load_and_validate() missing 1 required positional argument: 'doc_url'
The `load_and_validate` function was called without providing all its mandatory arguments, specifically the URL or path to the document to be validated (`doc_url`) or the schema (`schema_url`).
fixEnsure both the `doc_url` and `schema_url` arguments are provided when calling `load_and_validate`.
Upgrade
Version history
8.10.20260825112551latest on PyPI · released Aug 26, 2026
Audit
Dependencies
requestsrequiredUsed for fetching remote schemas and general HTTP requests.
ruamel.yamlrequiredYAML parsing and serialization.
rdflibrequiredRDF processing and transformation.
cachecontrolrequiredHTTP caching for requests.
mypy_extensionsrequiredType hinting extensions, especially relevant for code generation features.
mistunerequiredMarkdown parser, likely used for documentation generation.