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

Uploaded Source

Built Distributions

schema_salad-8.2.20211029004247-py3-none-any.whl (478.3 kB view details)

Uploaded Python 3

schema_salad-8.2.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247-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.20211029004247.tar.gz.

File metadata

  • Download URL: schema-salad-8.2.20211029004247.tar.gz
  • Upload date:
  • Size: 457.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 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.20211029004247.tar.gz
Algorithm Hash digest
SHA256 3f60d579244d952c8c62bb6b1cd3e1642fd60d338607196e487508c1fb76d168
MD5 f9ca617a2407f58a370f6d9e4c234627
BLAKE2b-256 5432b14075c794a3e7d2697341fbebbd06b4dfdf07d4ba967c2824ba80ef2533

See more details on using hashes here.

File details

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

File metadata

  • Download URL: schema_salad-8.2.20211029004247-py3-none-any.whl
  • Upload date:
  • Size: 478.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 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.20211029004247-py3-none-any.whl
Algorithm Hash digest
SHA256 ae82a31fba967be9995ab65069a2b59f632532fbf8d4d617304a09f051502faa
MD5 0d3918d58f14b08a049acbddcdc48d6e
BLAKE2b-256 f88495d845234c14788e858565d1dd6a1a1df1beb578b80bd0679b903fb4fc4a

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211029004247-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 fb6f5d0ab1ae08b6e435a87d0306d9a02fc602c7de6c6d200d6614bfd7d4d89a
MD5 2b6f80bdb6acd8802ccba89cb74762c7
BLAKE2b-256 b63457e890a72832f90b452acfa0d4a45ad36a10c46db5723f868bf02b55c022

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 641ee5403e1b4d930aa9fc76b24cd87d1edb1ba249cef3254a1a84126cc3f875
MD5 55a9409fafce7e32d01dbced8cf14521
BLAKE2b-256 3f173e9c8ea90702cef79a797bab73248683373ebbe02e25b7a2ca8e2fe92c05

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 2b664023278dc7234dc162bd3dd4dc030892bac2411f8455616ced720296457f
MD5 01497f303d4c042565d5a58155e15ae8
BLAKE2b-256 cc143bbd9dbcd36a57b769759fb9e30fadad7a133fb6b05cb0a1c74833b91386

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211029004247-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 904b90e04e1f4860e4b11971788128640dd6160ce6b8dfe2414511fc8e01de5e
MD5 1b67c17c18ae13364e201315a198a006
BLAKE2b-256 2630ecd3831471c018d2d4d50c13727b5aa92c91a624ac962216f06b456bdf73

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3c6a711b3854cc9ef2696ddba328a7ebdd17c030eae32c1005e57c8e6425bb5a
MD5 7414c520e35310a1e999014e9e4885e7
BLAKE2b-256 2a5c67a38ef71794dcf30e94839888069da56640a9c8291491c9f5b70076e14b

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 fb54badb16736ff081234f0351e5804aeeff417ac974a573af70f93138a6c3ab
MD5 b64944f01caef8143d227dbfa602073d
BLAKE2b-256 49d141856ed485f4d59da6ce857dc0140e1dd08fc7fe6fc9ed32965a9fbcaee3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211029004247-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3506ee655930fed4998a2547ae62e2fb2acc1c692ab99552c3ae2faf5d7edc54
MD5 46eeef3bbc61a1bfd3d7452fe39473b6
BLAKE2b-256 495efc01ab21c3eec85110228d9ee43da74a85f01eee32942dbfb54e6ad045a9

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 95b145bc92b9452dbac191cb08b6ab38c6eb28d5c76c50e1917a12a94ffb88ff
MD5 02fa76140d09258faa57003c86dfd333
BLAKE2b-256 5ac78a28ba04ac6c791ca0827efa07f7ec5539d0c0105c5694f899c8daf9b442

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 e85c940386a9c6bd2e88862c84a29047fb408f692e7eab0e7040a6abceff699e
MD5 22c2259ac4084aa3a80426aca2207395
BLAKE2b-256 ea428e7e25d37058917a8d232480794727fadf34ac9d7d3c2bd2e9431db234e7

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211029004247-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 02a9e3e88fdf65fb210ba70ebb6237ae895c58e4d5bdb49f0e16982e4da73671
MD5 b26ce15ad16a14b505e62707adbb594d
BLAKE2b-256 afec62b5032ab020d2f8162831e0e26d48bdf3de969dba3900e8891dba80d82d

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6f69c8ee6b6f8468bfcad2c1db487c26f2da245bb7c42337a1772e388cab27ce
MD5 538372d57e59f80fa7fac2acf7df5898
BLAKE2b-256 4ef90313166a8ae62f72c72bd20908435e58febec46b3b2a5936807214c333b5

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 ddd39f04d9f1bb4b563efb1a8f19130be935e0f24fcda7646c9e632499668d71
MD5 58f1f8f3471845f9f9ebd47000834344
BLAKE2b-256 db1fd0087ef4c070f4380c90443cf231b2170cb5d9fe5b205d307a645d841ae9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211029004247-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 71646d789806469b506d20acf27466321357edf41ea788489ee605da82a472f9
MD5 02eab83775e0d0a0bc951772daaac61d
BLAKE2b-256 2e83862f6e2f5101d33ffcf2e144aca4577867a9c9b9ca4df3e98b8db96bc9a6

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8de1f332a3bc5d472cd80f8366079a1e022c796cdfb14f41c60ca032bc27646f
MD5 90bd05935757c272f3feda9e3a44a6ad
BLAKE2b-256 0c741f8024451d811385108e15fcb862dad8947c56a00312caf939b9ed51f8f5

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211029004247-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.20211029004247-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 6124e5a79a595f06b12683813f93d40c712d77d91336881505c1f49b8da2ae41
MD5 281747e089c0d2b4714cedbb11e4a8ef
BLAKE2b-256 6876a087fc79a3311a0bce501ceb09a9230291d660c56297bd3b93d776b88326

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