{"id":5470,"library":"schema-salad","title":"Schema Annotations for Linked Avro Data (SALAD)","description":"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.","status":"active","version":"8.9.20260327095315","language":"en","source_language":"en","source_url":"https://github.com/common-workflow-language/schema_salad","tags":["schema","validation","linked-data","json-ld","yaml","avro","workflow"],"install":[{"cmd":"pip install schema_salad","lang":"bash","label":"Basic Installation"},{"cmd":"pip install schema_salad[pycodegen]","lang":"bash","label":"With Python Code Generation Support"}],"dependencies":[{"reason":"Used for fetching remote schemas and general HTTP requests.","package":"requests","optional":false},{"reason":"YAML parsing and serialization.","package":"ruamel.yaml","optional":false},{"reason":"RDF processing and transformation.","package":"rdflib","optional":false},{"reason":"HTTP caching for requests.","package":"cachecontrol","optional":false},{"reason":"Type hinting extensions, especially relevant for code generation features.","package":"mypy_extensions","optional":false},{"reason":"Markdown parser, likely used for documentation generation.","package":"mistune","optional":false}],"imports":[{"note":"Main module for general use.","symbol":"schema_salad","correct":"import schema_salad"},{"note":"Specific functions and classes are located in submodules like `schema_salad.schema`, `schema_salad.ref_resolver`, etc.","wrong":"from schema_salad import load_and_validate","symbol":"load_and_validate","correct":"from schema_salad.schema import load_and_validate"},{"note":"For custom URI resolution and fetching.","symbol":"Fetcher","correct":"from schema_salad.fetcher import Fetcher"}],"quickstart":{"code":"import os\nimport json\nfrom schema_salad.schema import load_and_validate\nfrom schema_salad.ref_resolver import Loader\n\n# Define a simple SALAD schema (YAML string)\nschema_content = \"\"\"\n$schema: http://json-schema.org/draft-07/schema#\n$id: https://example.com/myschema.yml\ntype: record\nname: MyRecord\ndocumentRoot: true\nfields:\n  - name: id\n    type: string\n    jsonldPredicate: '@id'\n  - name: message\n    type: string\n  - name: count\n    type: int\n\"\"\"\n\n# Define a document to validate (YAML string)\ndocument_content = \"\"\"\nid: 'my_first_doc'\nmessage: \"Hello, SALAD!\"\ncount: 42\n\"\"\"\n\n# Save schema and document to temporary files\nschema_file = 'temp_schema.yml'\ndocument_file = 'temp_document.yml'\n\nwith open(schema_file, 'w') as f:\n    f.write(schema_content)\nwith open(document_file, 'w') as f:\n    f.write(document_content)\n\n# Create a Loader instance\nloader = Loader({})\n\n# Load and validate the schema itself\nprint(f\"Validating schema: {schema_file}\")\nschema_salad_obj, _, _ = load_and_validate(schema_file, loader)\nprint(\"Schema is valid.\")\n\n# Load and validate the document against the schema\nprint(f\"Validating document: {document_file}\")\ntry:\n    validated_doc, _ = load_and_validate(schema_file, document_file, loader)\n    print(\"Document is valid.\")\n    print(\"Validated document (as Python object):\")\n    print(json.dumps(validated_doc, indent=2))\nexcept Exception as e:\n    print(f\"Document validation failed: {e}\")\n\n# Clean up temporary files\nos.remove(schema_file)\nos.remove(document_file)\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or a later supported version.","message":"Schema Salad requires Python 3.10 or newer. Installing or running on older Python versions will result in compatibility errors.","severity":"breaking","affected_versions":"<=8.9.x (all versions requiring Python 3.10+)"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions. Performance trade-offs are inherent to the validation methods."},{"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.","message":"Understanding 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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions (general schema design principle)."}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}