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

Uploaded Source

Built Distributions

schema_salad-8.2.20211020114435-py3-none-any.whl (477.7 kB view details)

Uploaded Python 3

schema_salad-8.2.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.6 MB view details)

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

schema_salad-8.2.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-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.20211020114435-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.1 MB view details)

Uploaded CPython 3.6m manylinux: glibc 2.17+ ARM64

schema_salad-8.2.20211020114435-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.20211020114435-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.20211020114435.tar.gz.

File metadata

  • Download URL: schema-salad-8.2.20211020114435.tar.gz
  • Upload date:
  • Size: 456.9 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.20211020114435.tar.gz
Algorithm Hash digest
SHA256 39c9b731f1304f041dc8fbb40bb91b89c3a5e0121e7ddf7b74e58fff505fcbee
MD5 d68a4f0eb7ab8073711c8e4e94e864b4
BLAKE2b-256 c7f1138fa33feed1c1efcc98cab10a0dce88a988e9d4a8def90d11e31e7594a4

See more details on using hashes here.

File details

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

File metadata

  • Download URL: schema_salad-8.2.20211020114435-py3-none-any.whl
  • Upload date:
  • Size: 477.7 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.20211020114435-py3-none-any.whl
Algorithm Hash digest
SHA256 86ba4111f598a97c63e164ba07b0cac214b4d9bdb135f94bab58c1a49eb3a924
MD5 92c1f20a818805d510e9a6c921f36b4d
BLAKE2b-256 1827327bcaf7263d6b49aefdfa3a3c23cd8605e897296b0e13b8a84819ff1f95

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211020114435-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e9867170cfd8209cb1be85e5a5760bcee058484f1f7103e01d151df813db5074
MD5 9f78a55ce3d6134763ef4d0b2bbaa53d
BLAKE2b-256 fc81c48dda3536ad8a3e246d9f5b45ec062f3122172a76a9c2e67f3057320516

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e608cb7093e67fcb7fab8e2311b18e814637595ec638fe092f05f8894d3cdba8
MD5 f1426c56c266129278980177d1ae5f57
BLAKE2b-256 a556e8169175ab1ae7fc7bd9504c4a2cbfe566d0128c77c43a8ca5c60668a827

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 17846215c9d7ed63ce461f40f6f70e0328bee59771a4167e3241b7d7c60e4a91
MD5 0022e777e259e59dcb48705e60efe484
BLAKE2b-256 4c2048cf60113096c0bd7fcd338e196f2e967560b42ded019e3589f76debf849

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211020114435-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 592dfee7991199fa5ae87a899332696a32f78ab17e3331a0f176115b32739f52
MD5 0b8ba4e7b3202057e4d7e040fdae3364
BLAKE2b-256 8084bcb6da55d7d53e331c5aa31e00fd24ac88ce4753dffaf74bd38b0dc2d5c1

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 89f90610b4d656bc243f85e51317e4f58cea00d90145de56307682c3504420f9
MD5 300b937aa868c434a0b3d383bcd5477c
BLAKE2b-256 8da565edf0a11716dc314b1dd4f67e1f5dfc6335a7545dd8ace83553d9c828c9

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 566ac77079327187917db7893a8515b0789891a97c90973c3e94a88e779a4573
MD5 6ad6dd7385e3027677d95af10488bd50
BLAKE2b-256 4b351408e5165858b8dee3285adae1dfb3e41e7267a51e4368ad1095c1dcb6ca

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211020114435-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 444afb4c0d3fb0140244ec39904020e8b6b310f0873f29bddaa6f607ab4219b7
MD5 4c17a3dba0e7c2d43fd7ac846cdaa0f5
BLAKE2b-256 60da8fd7aa74fb7efb001348b0f155fc2e3c53630de5b50dcabd95a208ca0eb5

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ed1a2f1d2b6ef31f4ebb05cf7072c2fccee499065c7bc8dba07346208bde6012
MD5 3e09b77f0df4903595a27a10cde80895
BLAKE2b-256 243583d0c28be2c7a9cfa8363cefadb394834d360ee1ef909f1bf56d6a71a4e7

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 ddd79d7b6d44b3b6947726780ded41a8763aac75a34282a3ad1cb7a822a64b74
MD5 492922dd9296299f90f883cc83bcd5ff
BLAKE2b-256 b81e2bd9b55f4872d87a55de228f2f6ecbb2a95d487a3d430426e88fff143145

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211020114435-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ddda8384d89134d80886e0fc707b5614003b96ac0ceb9f3757aa6f997da5587f
MD5 d97469c504d0440c6fdce1f612399351
BLAKE2b-256 405d9798902dcce978043da710d590b734e93f218cbaeba73f276baef7130147

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d21bda5ef3a57239928a58726efc91f583e661d0a0d985a66084288cace9b632
MD5 68e57edb8e2db976798a04aeb99e0f23
BLAKE2b-256 382610f0ac3624aa8a2a12ca10254a4238aab8000b46880fe41caba254f4e4ee

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 722b5a3a58d804250ddcd8b84898e48879b6941b45fe32d496558d264fc9e997
MD5 cac4f147016f3374925fdf2f2bec254a
BLAKE2b-256 21de40be980b11c20c428f19872046d8bc8e4845970eddca7d231eaeaa896a1b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211020114435-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e8c568ea7241f994ddcc91e3b39f6161f7086736e827073b21a2d85145ab06b3
MD5 751d09702f942ab2aac5faab0a2ed979
BLAKE2b-256 7111c24d7c8493e9e363845703e956bfeb5f1f01adcc5daf27b2350355ecb94b

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fc006ab067c197c186efa3ac008b0b4910c7d95ff89d5f6f8111d7411533145c
MD5 62aaaa4cb1db7c363a9922bb585bbd68
BLAKE2b-256 a0a6ae13d406cc882427024fb91507bafa54b5765a5811de6cda6615710172e0

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211020114435-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.20211020114435-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 83a7a86d7f93bb5190e82d51d3cd4c1df037a76157d2dd18a5f8d3aa10c84652
MD5 25092329a7658a70c56a7c607f3f2120
BLAKE2b-256 5b9d6db0f2d67099b5cdec56c971cd1286615a63f5c024e335cbad2d54cf214a

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