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

Uploaded Source

Built Distributions

schema_salad-8.2.20211116214159-py3-none-any.whl (479.0 kB view details)

Uploaded Python 3

schema_salad-8.2.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-cp39-cp39-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.9 manylinux: glibc 2.12+ x86-64 manylinux: glibc 2.5+ x86-64

schema_salad-8.2.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159-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.20211116214159.tar.gz.

File metadata

  • Download URL: schema-salad-8.2.20211116214159.tar.gz
  • Upload date:
  • Size: 457.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.2

File hashes

Hashes for schema-salad-8.2.20211116214159.tar.gz
Algorithm Hash digest
SHA256 0c737af600e0a03dd97c93b9867e862463b65d95580ba711fd22f542bc80ad00
MD5 96d7c30c2e2ab758259c8ea7b2cb3a6c
BLAKE2b-256 c073960e7a4ba969d485578e2a50dda5369b381f933d60e31d984cc55002d7e5

See more details on using hashes here.

File details

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

File metadata

  • Download URL: schema_salad-8.2.20211116214159-py3-none-any.whl
  • Upload date:
  • Size: 479.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.2

File hashes

Hashes for schema_salad-8.2.20211116214159-py3-none-any.whl
Algorithm Hash digest
SHA256 dab5ab1e21e228b47f96f313a60644ab0506724423ac56c900177dc0852b3e7d
MD5 cd492a97d3db50b618a5cfda013ec744
BLAKE2b-256 0091b9a3f8bd97d8f3b5af0126e1f0e97e73a1e7cc7ea217f29860e2e588085a

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211116214159-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 9d4ab4de11b87ff51c648b3769e331e0b5fb5c7b2083cc99c8fca648e42c7fc0
MD5 25abf4402d1fd5daa7501fbef2cd93e6
BLAKE2b-256 14a450007bd12b65846d9a88c584ed4642292124ee08c5298101660d0be6a7b6

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b3b7ab8ee71d530cec26477922ab5e3363b534a6e861b6736bc1f11f4e480806
MD5 7e9cd806edacdaf2830ed73b491f8581
BLAKE2b-256 1b2c1735acaeedb4d2699da3d4a0acf748f62b8d60d095de8d41a6bd292125e4

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 a9e80b482387e5e529748fa48c44835fcd4eb45611a21283a59855921a86106e
MD5 33e5d3dee5c9f6e11924f0393b9868ce
BLAKE2b-256 8ec34e2e10405e883231e99b72c870ceea680252b765ec4d02b93d55bc752143

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211116214159-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 f60f641c7c376d0bc8772f33186cfebdff2bd7d990955bad503444c566afe4c6
MD5 5ee0b1c36dca9224d74605ed7d120eb0
BLAKE2b-256 1d35035707923424ede0aaafe761424fc37b650f2edbd531828137eacd86a77b

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 83cf696e9a40511fe2b2fd7af7ff00ff53b5f6d3f6af4a0738136da5f3decf89
MD5 1aa3e95252bc2b25857ce957ddf37f1e
BLAKE2b-256 b7113e4dad4cfc793617e3f4df9ea82c6b3418d5aa5ae37cdee6d212a948ae16

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 2511e28367dcd638fc7bf4f75cefcba3527eb0f36b2096f7e985ec0cef11a262
MD5 cf35ba6b537e488f67b707314d871901
BLAKE2b-256 9e109fb0fa5045b1a4edb5f9c910a8ae98ef31e92292ed526376f63fbf76dc5c

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211116214159-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0641e88afccf97d24be34ba712d68205c4da07555332e73f7a0dfc00c0587b53
MD5 e1ff9f858794b10d1bfa0b6ecfffd219
BLAKE2b-256 65394cf7fe7a4a66b03f869c67d0b20ae684e95bbcfac4d6e7b488eb7bc7528e

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 45c96ab594d322977424fca941996a5c3a7540801160c0d0aee1a34c8bc9c5ac
MD5 2ffce25e6e9eb5f1041157c0aac656b4
BLAKE2b-256 97e9c9fbd012999f656924392a1c4b815b5e0aa1166d4a5cedbe2eb97580f2fc

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 67be0044387ae02cac18b607bd0fb1dae16d6a26fc575c75c95ebd68b137749e
MD5 7aa6b083942c3f30fd8172a5b495543c
BLAKE2b-256 6151e169bb62ec2e5ea414dda495f58ed9fb257164b96302c06de33e2717240d

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211116214159-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c4981f020b6ae84c2be1f43ec5be94d3aa5a6a5b0f593b9f96c984b96267d2ea
MD5 b64b34d5283f4e0e06a28e316fe7bb14
BLAKE2b-256 e371b1703876f0e811e3ed00a3452026c24848b1fa2fe5e230b6273a98700f78

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 67632a418b2508e883757c8b5d7f52bcc3ec87fc96a0b3a519b433a556e0d97d
MD5 fd2636d62c0a42258845b684557dd6f8
BLAKE2b-256 0ed85722029d5425d834e894ddeb73d73f30df54d81d47997793dec87ed736fc

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 b41848b58d7b742b3eb17e45e7b2dea548fa561c022765d3fde82a746d02457a
MD5 4c354abacaa20d896932486148764e0d
BLAKE2b-256 274eab9558e3d04c79cfc844b0b6f76c5b2aee36c9ce8276339151a07b0a11c3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211116214159-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 70ac01c3d1f06fa98ee6311600d07e53dd746d0a9ae494e53b25261e64b61a4c
MD5 e97caab48d5806f33438cd0dd0b52516
BLAKE2b-256 66171c32f77d18fb4c3efa99abaa8166e18bddb3d06eb40a179556ed27871920

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6e5237cb825f91ee81b46ebb7078be1cc3fdd09fc86d938b63887243fcacf439
MD5 bbef0132b47473934900d0e5030bc9b0
BLAKE2b-256 a0d5ceb12771bc336e4bfc28de63a28818f463f0e0071866c2d1a5956181cefd

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211116214159-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.20211116214159-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 39f8e3d7593117de772663f6ae67780e5df6c7366d0824fd48fc1fbde963e0a5
MD5 3006613d2466e444a2d30de9a7ff7216
BLAKE2b-256 8288657b6b00f8644d07cd4b6e25caf5627763b2128f5c840050785510ef9ccb

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