Registry / serialization / schema-salad

schema-salad

JSON →
library8.10.20260825112551pypypi✓ verified 22d ago

Schema Salad (SALAD) is a schema language for describing JSON or YAML structured linked data documents. It provides rules for preprocessing, structural validation, and hyperlink checking, and supports rich data modeling features like inheritance, template specialization, object identifiers, and references. It also enables documentation and code generation, and transformation to RDF, bridging document-oriented data modeling with the Semantic Web. The current version is 8.9.20260327095315, and it appears to have a frequent release cadence, often multiple patch releases per month, indicating active development.

pip install schema_salad
INSTALL
IMPORT
SIG · SCHEMA-SALAD
S
schema-salad
serializationpythonv8.10.20260825112551
Install
5.1s avg
Import
30ms
Disk
57MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.032s · 56.4MB
glibc
py 3.103.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.
fix
Upgrade 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.
fix
For 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.
fix
Carefully 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.
fix
Implement 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.
fix
pip 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.
fix
Verify 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.
fix
Adjust 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`).
fix
Ensure 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.
Agent activity
11 hits · last 30 days
node
6
OpenAI (training)
1
Resources