Skip to main content

Linux Build Status Code coverage Documentation Status CII Best Practices

Schema Salad

Salad is a schema language for describing JSON or YAML structured linked data documents. Salad schema describes rules for preprocessing, structural validation, and hyperlink checking for documents described by a Salad schema. Salad supports rich data modeling with inheritance, template specialization, object identifiers, object references, documentation generation, code generation, and transformation to RDF. Salad provides a bridge between document and record oriented data modeling and the Semantic Web.

The Schema Salad library is Python 3.10+ only.

Installation

pip3 install schema_salad

If you intend to use the schema-salad-tool –codegen=python feature, please include the [pycodegen] extra:

pip3 install schema_salad[pycodegen]

To install from source:

git clone https://github.com/common-workflow-language/schema_salad
cd schema_salad
pip3 install .
# or pip3 install .[pycodegen] if needed

Commands

Schema salad can be used as a command line tool or imported as a Python module:

$ schema-salad-tool
usage: schema-salad-tool [-h] [--rdf-serializer RDF_SERIALIZER] [--skip-schemas]
                      [--strict-foreign-properties] [--version]
                      [--print-jsonld-context | --print-rdfs | --print-avro |
                           --print-rdf | --print-pre | --print-index | --print-metadata |
                           --print-inheritance-dot | --print-fieldrefs-dot | --codegen LANGUAGE |
                           --print-oneline | --print-doc]
                      [--codegen-target CODEGEN_TARGET] [--codegen-examples DIRECTORY]
                      [--codegen-package DOTTED.PACKAGE] [--codegen-parent PARENTS_MAP]
                      [--codegen-copyright COPYRIGHT_STRING]
                      [--codegen-spdx-copyright-text SPDX_COPYRIGHT_TEXT [SPDX_COPYRIGHT_TEXT ...]]
                      [--codegen-spdx-license-identifier SPDX_LICENSE_IDENTIFIER]
                      [--codegen-parser-info PARSER_INFO] [--strict | --non-strict]
                      [--verbose | --quiet | --debug] [--only ONLY] [--redirect REDIRECT]
                      [--brand BRAND] [--brandlink BRANDLINK] [--brandstyle BRANDSTYLE]
                      [--brandinverse] [--primtype PRIMTYPE] [schema] [document ...]

$ python
>>> import schema_salad

Validate a schema:

$ schema-salad-tool myschema.yml

Validate a document using a schema:

$ schema-salad-tool myschema.yml mydocument.yml

Generate HTML documentation:

$ schema-salad-tool --print-doc myschema.yml > myschema.html
$ # or
$ schema-salad-doc myschema.yml > myschema.html

Get JSON-LD context:

$ schema-salad-tool --print-jsonld-context myschema.yml mydocument.yml

Convert a document to JSON-LD:

$ schema-salad-tool --print-pre myschema.yml mydocument.yml > mydocument.jsonld

Generate Python classes for loading/generating documents described by the schema (Requires the [pycodegen] extra):

$ schema-salad-tool --codegen=python myschema.yml > myschema.py

Display inheritance relationship between classes as a graphviz ‘dot’ file and render as SVG:

$ schema-salad-tool --print-inheritance-dot myschema.yml | dot -Tsvg > myschema.svg

Codegen Examples

The examples in the tables below are helpful to see how to use the output of schema-salad-tool –codegen in different languages for loading and/or creating/editing/saving objects.

First set of examples is using the CWL v1.2 schema:

Language

Repository

Serialization Example | Deserialization Example

Python

https://github.com/common-workflow-language/cwl-utils/

create_cwl_from_objects.py

load_document()

Java

https://github.com/common-workflow-language/cwljava/

(Not yet implemented)

PackedWorkflowClassTest.java

TypeScript

https://github.com/common-workflow-lab/cwl-ts-auto

Creating, editing, and saving CWL docs with TypeScript

Loading CWL documents with TypeScript

.Net

https://github.com/common-workflow-lab/CWLDotNet

Creating, editing, and saving CWL docs with .Net

Loading CWL documents with .Net

C++

https://github.com/common-workflow-lab/cwl-cpp-auto

cwl_output_example.cpp

cwl_input_example.cpp

D

https://github.com/common-workflow-lab/cwl-d-auto

How to use

How to use

Second set of examples is for the Galaxy Workflow Format 2 schema:

Language

Path

Python

https://github.com/galaxyproject/gxformat2/blob/master/gxformat2/schema/v19_09.py

Java

https://github.com/galaxyproject/gxformat2/tree/master/java

TypeScript

https://github.com/galaxyproject/gxformat2/tree/master/typescript

Quick Start

Let’s say you have a ‘basket’ record that can contain items measured either by weight or by count. Here’s an example:

basket:
  - product: bananas
    price: 0.39
    per: pound
    weight: 1
  - product: cucumbers
    price: 0.79
    per: item
    count: 3

We want to validate that all the expected fields are present, the measurement is known, and that “count” cannot be a fractional value. Here is an example schema to do that:

- name: Product
  doc: |
    The base type for a product.  This is an abstract type, so it
    can't be used directly, but can be used to define other types.
  type: record
  abstract: true
  fields:
    product: string
    price: float

- name: ByWeight
  doc: |
    A product, sold by weight.  Products may be sold by pound or by
    kilogram.  Weights may be fractional.
  type: record
  extends: Product
  fields:
    per:
      type:
        type: enum
        symbols:
          - pound
          - kilogram
      jsonldPredicate: '#per'
    weight: float

- name: ByCount
  doc: |
    A product, sold by count.  The count must be a integer value.
  type: record
  extends: Product
  fields:
    per:
      type:
        type: enum
        symbols:
          - item
      jsonldPredicate: '#per'
    count: int

- name: Basket
  doc: |
    A basket of products.  The 'documentRoot' field indicates it is a
    valid starting point for a document.  The 'basket' field will
    validate subtypes of 'Product' (ByWeight and ByCount).
  type: record
  documentRoot: true
  fields:
    basket:
      type:
        type: array
        items: Product

You can check the schema and document in src/schema_salad/tests/basket_schema.yml and src/schema_salad/tests/basket.yml:

$ schema-salad-tool basket_schema.yml basket.yml
Document `basket.yml` is valid

Documentation

See the specification and the metaschema (salad schema for itself). For an example application of Schema Salad see the Common Workflow Language.

Rationale

The JSON data model is an popular way to represent structured data. It is attractive because of it’s relative simplicity and is a natural fit with the standard types of many programming languages. However, this simplicity comes at the cost that basic JSON lacks expressive features useful for working with complex data structures and document formats, such as schemas, object references, and namespaces.

JSON-LD is a W3C standard providing a way to describe how to interpret a JSON document as Linked Data by means of a “context”. JSON-LD provides a powerful solution for representing object references and namespaces in JSON based on standard web URIs, but is not itself a schema language. Without a schema providing a well defined structure, it is difficult to process an arbitrary JSON-LD document as idiomatic JSON because there are many ways to express the same data that are logically equivalent but structurally distinct.

Several schema languages exist for describing and validating JSON data, such as JSON Schema and Apache Avro data serialization system, however none understand linked data. As a result, to fully take advantage of JSON-LD to build the next generation of linked data applications, one must maintain separate JSON schema, JSON-LD context, RDF schema, and human documentation, despite significant overlap of content and obvious need for these documents to stay synchronized.

Schema Salad is designed to address this gap. It provides a schema language and processing rules for describing structured JSON content permitting URI resolution and strict document validation. The schema language supports linked data through annotations that describe the linked data interpretation of the content, enables generation of JSON-LD context and RDF schema, and production of RDF triples by applying the JSON-LD context. The schema language also provides for robust support of inline documentation.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

schema_salad-8.10.20260814121804.tar.gz (597.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

schema_salad-8.10.20260814121804-py3-none-any.whl (650.3 kB view details)

Uploaded Python 3

schema_salad-8.10.20260814121804-cp315-cp315-musllinux_1_2_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.15musllinux: musl 1.2+ ARM64

schema_salad-8.10.20260814121804-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.15manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

schema_salad-8.10.20260814121804-cp314-cp314-musllinux_1_2_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.14musllinux: musl 1.2+ ARM64

schema_salad-8.10.20260814121804-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

schema_salad-8.10.20260814121804-cp313-cp313-musllinux_1_2_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.13musllinux: musl 1.2+ ARM64

schema_salad-8.10.20260814121804-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

schema_salad-8.10.20260814121804-cp312-cp312-musllinux_1_2_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.12musllinux: musl 1.2+ ARM64

schema_salad-8.10.20260814121804-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

schema_salad-8.10.20260814121804-cp311-cp311-musllinux_1_2_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.11musllinux: musl 1.2+ ARM64

schema_salad-8.10.20260814121804-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

schema_salad-8.10.20260814121804-cp310-cp310-musllinux_1_2_aarch64.whl (1.6 MB view details)

Uploaded CPython 3.10musllinux: musl 1.2+ ARM64

schema_salad-8.10.20260814121804-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

File details

Details for the file schema_salad-8.10.20260814121804.tar.gz.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804.tar.gz
Algorithm Hash digest
SHA256 fdb1a52c8d0ffa6f984d47b516a3bff882c7aa4a4a957408cad42092cad4a923
MD5 3cf5acae564cd047e74617b1a22eac53
BLAKE2b-256 1e8d3014f4ff18ff920036191ef396d0286a1af8c97e2292c1e44254854dd3ee

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-py3-none-any.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-py3-none-any.whl
Algorithm Hash digest
SHA256 7e4e89a4cf49c40dde97d7de53c865803738b77b9229676293143614b1af2400
MD5 2c20c7f2d6421d4e4893232bbed1db13
BLAKE2b-256 1c0a09e00d8f0e0c3ba3abeb2e3b2ac0f5209283ea1766251c8c2269726c8dad

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp315-cp315-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp315-cp315-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 730fe050b73246b71c8cf46ef2b5508ef54847c0beae453b964f2bbb1b5e07f6
MD5 b774b6d98688450a3b367c23c67fa9c0
BLAKE2b-256 bc5baa412b1aeae30c48e740d2d33108ca5f36dd2e8333776c7cf0c55d9ceb1b

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 82bf8da2dab2a57119dfd62e2d0af19816d92337976f63b0a78bc4ec33b36275
MD5 8f95cabbf5667318139e9103f0038937
BLAKE2b-256 0719ad8f20d5393e7a76e7ec329debc55cf35e804458271dec42671a336f1b44

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp314-cp314-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp314-cp314-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 011d11365781eac43733aaeac86112b1e9c56266141d188e2c7bac75333f65d2
MD5 66b31f6dd426c2f6fa20c66e59ad66ef
BLAKE2b-256 631a180b74af34d2329e68361fdc3051521e217632f3cda1e0784829de4a0494

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 2bd3a7a83731d74f5ea7cb5650fd640d7bedc689b259c2625c24ea8cca1302c4
MD5 e3af7fd8f83ea424a7b98f6e52da32bd
BLAKE2b-256 3c54a0cd1761037ee5ad8c1b5e842ed56732beaeaf8baea2fa66d1a2b6c253ea

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp313-cp313-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp313-cp313-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 880e02cf7f5fa68bceef19ea0fb90c3cf5ef233870e4e6402de225ec1532bade
MD5 a69b773e367aaec24be8477b478a3b40
BLAKE2b-256 43c2dc4566d5f02bc4bd13f00539adf00ebc7c8ae7fef16be3fe33899f3745b9

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 c92fdf69d81ad9ecb6970c69dd9d16a94f574fb4ea803db97ee7d20bfa17f0dd
MD5 446ca605fdabbdf197d69c74d6a4ea8b
BLAKE2b-256 6ebe98e86221583fe04087073fb3a0d0f9e449084f4b3c584184efff0908519e

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp312-cp312-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp312-cp312-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 e713c6853abe696e421ab595d94c8a4158db8ebc6330ef9957a9283b2b670cf4
MD5 be57678b3bff916a9107fe93b741afa1
BLAKE2b-256 22eaa57a600af051f87731914350c305c0bf6eea6a7975722c4e449e15496852

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 e278108dc81cb508d0d7bd864e2ecf309845d2848b7176c2ba72a388c71749c0
MD5 6feafa5b442993ecf79de26fdf8be990
BLAKE2b-256 6404539cd0d390f0af2728469733bc70192cc108d60d968ad08ce76167a1bb07

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp311-cp311-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp311-cp311-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 8775ea8a6a9289f8398779b088ac5f1d409481347c559d8e43575ecf22b38cbe
MD5 b69fe1dfa9089f7e4fa1f08f68806e95
BLAKE2b-256 f4bcf883362282ea49ba96f8c42c49d589dcf4e2f3ddae33603cfa39f49d9379

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 71c474288d9a7cc6ac53ae5fa6f07c5ef252076eeb63bc46b511f0296e53f97d
MD5 ba3998676ace608af00515ccfabc5dc4
BLAKE2b-256 3dd651b9712682343bb3e0c2fe3841b63579474156c198456ce3ddf7eecca502

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp310-cp310-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp310-cp310-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 f734257df9db75dadec3f9f0926d66657748e627f95f65740c78114ae37508c1
MD5 77f1b139f01dd78e950585073a188af2
BLAKE2b-256 7b3cbb53d1238071ab16e4a1f31c5a1e94f8c806a628a963981541e79a611c95

See more details on using hashes here.

File details

Details for the file schema_salad-8.10.20260814121804-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.10.20260814121804-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 be8b1060c84549f1e65dbbee00b4b940957a5fbde53451fc288693792269c4ff
MD5 8af4e0f92a86103e8d357898e1a58455
BLAKE2b-256 cf15b236bf9f4a21c5af0f84cd68e7810f83e404d953b3569eec51fc29403b3f

See more details on using hashes here.

Release history Release notifications | RSS feed

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page