Skip to main content

Schema Annotations for Linked Avro Data (SALAD)

Project description

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.6+ 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] [--print-jsonld-context]
                      [--print-rdfs] [--print-avro] [--print-rdf] [--print-pre]
                      [--print-index] [--print-metadata] [--print-inheritance-dot]
                      [--print-fieldrefs-dot] [--codegen language] [--codegen-target CODEGEN_TARGET]
                      [--codegen-examples directory] [--codegen-package dotted.package]
                      [--codegen-copyright copyright_string] [--print-oneline]
                      [--print-doc] [--strict | --non-strict]
                      [--verbose | --quiet | --debug] [--only ONLY] [--redirect REDIRECT]
                      [--brand BRAND] [--brandlink BRANDLINK] [--brandstyle BRANDSTYLE]
                      [--brandinverse] [--primtype PRIMTYPE] [--version]
                      [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

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 schema_salad/tests/basket_schema.yml and 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.

Project details


Release history Release notifications | RSS feed

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.2.20211103155537.tar.gz (457.4 kB view details)

Uploaded Source

Built Distributions

schema_salad-8.2.20211103155537-py3-none-any.whl (478.4 kB view details)

Uploaded Python 3

schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.6 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ ARM64

schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (2.8 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.6 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ ARM64

schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.4 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.17+ ARM64

schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view details)

Uploaded CPython 3.7m manylinux: glibc 2.17+ ARM64

schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.7m manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.7m manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view details)

Uploaded CPython 3.6m manylinux: glibc 2.17+ ARM64

schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.6m manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.6m manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

File details

Details for the file schema-salad-8.2.20211103155537.tar.gz.

File metadata

  • Download URL: schema-salad-8.2.20211103155537.tar.gz
  • Upload date:
  • Size: 457.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.5.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.0+

File hashes

Hashes for schema-salad-8.2.20211103155537.tar.gz
Algorithm Hash digest
SHA256 97fd009cdc591a27d24021392ccbb76de47645f27e32626cd3f68c3302ddc1f4
MD5 88e7e4d742d422e7b7f212dd4709aac6
BLAKE2b-256 e3e5b56d1938ddefc6c9ab5ec80e543bf3e63223f5e47ddad1cd0591ba882ed3

See more details on using hashes here.

File details

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

File metadata

  • Download URL: schema_salad-8.2.20211103155537-py3-none-any.whl
  • Upload date:
  • Size: 478.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.5.0 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.0+

File hashes

Hashes for schema_salad-8.2.20211103155537-py3-none-any.whl
Algorithm Hash digest
SHA256 b0d15c7591748c35ea6b99a3f681680696b50e81106501b6f9c98cf0f29dcac1
MD5 85ff283924120d5a8029721511bcc3db
BLAKE2b-256 d6b7aced2ae16beac32bfacc643dcb575fec7d5c93e4dbbc5d2fe2eea2d6f29f

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 274c173fbb13fe19e71a75d8b32b0f4a4d15582908d1dd4783519ee3639e7d6c
MD5 89f7625f11d1ea0e26af449c84fbb777
BLAKE2b-256 cc2124c650bacefb1af9c58e23e299fd84b4f02b0ae6662a27149938abf57df9

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1d0df7b4c376b48365506d2175bb6fc6a26780d547278d5531644a30d2bc169c
MD5 45b72d90a9fdd83afb9900f298c1424e
BLAKE2b-256 0122d64146b36481ab6e1d7648ad9e96b8d5e3a7ebf431f48ecf6e83efcf5530

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 ec99166fde372eddc9f57f96e884f629894b3263f705c9e7db652ae239964283
MD5 95500ffbae33ea8e1ca32c1855f75550
BLAKE2b-256 bf8256c75b5544e00cb543cbde823d07865a63897d926fd1d823b91ee52d89cf

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 f128dfe1b98ced3146376e5d6f5d4dd114917816bdd36bc61cfb9a156ec5aba4
MD5 844a2bbfda74bec52dd609d532d49d56
BLAKE2b-256 04b606a78811b6092bfc8e5f3f629077a9a84debc72579f6cbb30196379ebc3b

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 61e69ed89784b2935dc4ff539562ec1d65189fe2831755320b5ff62f559e2252
MD5 f1c2b89a3b2236e0f742672a08863642
BLAKE2b-256 63e3027f93c62ea26ee21e0f8999d0c360501e5f446850d7cd17a55552f1f218

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 4844c00ebeb441a9e6eaa2c2e07acdcdfff7a60c9e5c9130a38b81c78b992266
MD5 8c6082a6aa2dd21e0ba1cff335255043
BLAKE2b-256 7780162eac18cfc824d1a443c1b26d9366be55fdd4e86fe90c4f82975adbb4e9

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 cf0ed3bd3a4e97631dabc9730f6642ddd8c80bd7ff917690c90e22d4677e11fa
MD5 d268915a3b5f2829d7d6d2adf54b4db5
BLAKE2b-256 74545f828f0dfb251855e176ed482fa2c746bfd076bd8c80088b76fd4dcf9c1d

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 999f9afcb6976017470f35622b3b635730eda58e81fe959e57279be1f5390889
MD5 417b5978f170f71957103a75c95e06f0
BLAKE2b-256 87c3976595c75bf9a47406ee69e50705afe60e0f50225ebeac77906363006fed

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 c31a4f58dba803210763e90c23f203d1ff9bec420f9c7ee7db9b552e69509074
MD5 582c9b8048b29decc9b24c0103d67747
BLAKE2b-256 364900bde2648b5903ba8d6764c699b1fe909e204e2eecdd40fdd8d8a6ae9085

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0335bbba2fd74bbf3093eb139232a99cc4a1c4eb1df7a894ddbc529536dc7c8a
MD5 c9c83afaef0e94387597fffef923e182
BLAKE2b-256 ccf4a1e112ed9f694d69a5d8bfcf49e36429e5281ce3a2cb638f4f4aaff7bc56

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 065e3c523ee07241f657469c7339d3d0b77847ffdb1eccdee37e9ba20d781edb
MD5 15816d24c78c923942bb428768d6536d
BLAKE2b-256 70e1d5bc1b0c109bcd9e4fde4438882f4960fc97a8a6e96cf2358c8a429da351

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 85eef37ca6708f2df1d6a12689f233e448d06291407257d2152e0b2a824dcd5c
MD5 15c8387a634da47784687d368c0fcc93
BLAKE2b-256 0d6e98bfbcf2bcddc3f8e4a8763a9eeac45b82dd8f7c1fe5c36ca34fee89ab41

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 fe92c1ee5cac72225253b7268c724ffc0d72b32844d40779b3813754c69933b1
MD5 3ddf3fe29f7cd4c0bcad6d482893b09d
BLAKE2b-256 44592cc738c4581b9d2855ac42b70d010d5702a730fc9b1e5c701ee0d1f9630e

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 635762ea61b9ca6850bf56568d51919fc8d499ff33b783f8e85479d0fdf45334
MD5 94691329cce0566c8fe44df3510f58e6
BLAKE2b-256 bd34465951e9773826055301641207a7a9f450e9840bfb1cb2f6625c7917f147

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl.

File metadata

File hashes

Hashes for schema_salad-8.2.20211103155537-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 6381e22c1b9d87ea0772fe48ca9544f5fe897f704643b7eaa56634340fd43f70
MD5 451e8d78922cb2264ebbcf9b8a312352
BLAKE2b-256 effbef451440679f68c485276cd4cf1a80ec62a6074cc83e60ec821f96bef012

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page