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

Uploaded Source

Built Distributions

schema_salad-8.2.20211104054942-py3-none-any.whl (478.6 kB view details)

Uploaded Python 3

schema_salad-8.2.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942-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.20211104054942.tar.gz.

File metadata

  • Download URL: schema-salad-8.2.20211104054942.tar.gz
  • Upload date:
  • Size: 457.6 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.20211104054942.tar.gz
Algorithm Hash digest
SHA256 d5cacac8038df226416313fa6e18f43315777d2a670a1dcbaa9f31f7528b053f
MD5 2aabefdec710f686092935f3a69d1072
BLAKE2b-256 82dcacef3e8f8d5fccd47148e6d8bc5d9072b4368006e1dbdbf1d0a28cb72a96

See more details on using hashes here.

File details

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

File metadata

  • Download URL: schema_salad-8.2.20211104054942-py3-none-any.whl
  • Upload date:
  • Size: 478.6 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.20211104054942-py3-none-any.whl
Algorithm Hash digest
SHA256 50f8665572ac9d17d36d9fd846b4180e04aae9a473d5aa9e4cc3479469186869
MD5 6ee5e3acc4a78b00422a15ab9abc2090
BLAKE2b-256 e32c55a068b5edfde81793386cb764059a7925f757579f086a47c06ab013c958

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211104054942-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b3bcb7742e12424e0cf0e0daa7980535fa9ffb8b27b1d5e94e3877dd94cd0137
MD5 5a7becd3d6a6af319d4c1802d1d49f20
BLAKE2b-256 434b96c9d80533b14874170fcdaa5d261ec84411900e8376ea9368aa60a917f0

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f96795f31287f238c5e6e0a5e415f19d4a40a6d5db87482a0dfc80c9fa8e6da4
MD5 cf06e321ede39a5d7672dc0aa80c9ffe
BLAKE2b-256 26050929f46d7c1123dd89e4d6dd17557d0d249d787a540a515c329cfee1300f

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 34d6e783fd8ff44258fda132f6e2953547a78b9c813833a0e96e979422630ad2
MD5 01bee654b4d62da2ba1e3014b14f6150
BLAKE2b-256 ef0c8c17f7a3136ee628ed75859096bc49cc1864d04ccccce1185166e0dea77d

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211104054942-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 33c664c0ff8f97808c606cb8c25c1a2c849d7e5cea362e0db23256be4e734ac9
MD5 adb038051fd33834b02a7df8a01c905d
BLAKE2b-256 ad1e6667c9bbe0bfa06fad16a9a667006af95e0c214380e5470cdb2d1081c188

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 98ea6a211731b9cf968a01afe19a745b05575fd93886c9e5785f277d32e330da
MD5 58dd1a40c0dc8afa7111fda67781b7d4
BLAKE2b-256 ea578bb243b6a1570790d5701fb41b619808c0b321248c850b547a7cd17d288c

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 a2fe3c78526bb9199d07e3f27101ae8a18e97c6fa1452d288828d568ede25390
MD5 1baf9723efcc14601680766eaaf74ba7
BLAKE2b-256 17a9ec8fe1c44147cab69546f8cbf5d044e286475d710f6022a81ef9be717822

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211104054942-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ad61ee42c6a71d4baa442cfc7d575861c993a99d7daa281fa31a8228597463a5
MD5 5a3cff49a0adc0406bdadc912e0aa736
BLAKE2b-256 1d9a6e0e0d35945ef37872c89d8e0ee5ad75311ec16a2a2493f2c45fccbc8eab

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 258ff2a2f8918781e6572db495ec42f78affb24a0184f3dcdc3d2a951f75fe98
MD5 a02b6f269c0a66a9720222f2cf111d35
BLAKE2b-256 37efba5e9dfcef72e73803ead46954bb0b773df248579a6865feecbd094725e4

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 a1108d43b5f7d8f774c441e08bb32bdeadd3dfe9235ec4e1b1da1ed051e12b02
MD5 64b3bd9dfe2988ea2109b78ed790e2f9
BLAKE2b-256 86f1b4c3702f0fc7190d817bd1a368780b36a945729b08c166b548fcbee3da95

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211104054942-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ee655a82c2b72bb7869b0046601476e8f1e48c49cdd70f0a9b279c1debbd4efe
MD5 9b16ba37bad206b5eb7e92387067f68a
BLAKE2b-256 79f79e888d14f3cc1553088ed049e9316af9c642fac704cd165464d7865be016

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 86b833e084db9c682d99f444df32ec9fe4e448de2dd45806a655134372a35176
MD5 8a52da55c5f488245d6baaad862ae833
BLAKE2b-256 1b7b4ff4a9811524cd1006f96b0cfe1ffd457d06c65132f3f36318dd97ad8cec

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 3d27edb0e48017a58094934e88b8a17df82d25bc3004c50b5dc65cd40af6ed26
MD5 325d18b60324008c88e3376da7e166a6
BLAKE2b-256 c2a951ff3d86bfa11355dc88d74f76c467e7ee1bc5257a798d611491e7986028

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.2.20211104054942-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 168705b291933fe279f37b3879c7a71575bccec740fce371e748287f839f4071
MD5 ba4ea3f604b24be418d2a2fbbbdce167
BLAKE2b-256 b0e5d2ffc1a33cf1059760e2fc3a4a5fa1571f4300b5b4cff004b2f388eb712c

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ad49a6f2b7985a2dab3abb94c165c64f3d609525b2c771f48c5ae506f6b09230
MD5 925bdc93738cf8d32b135eca7f7264d8
BLAKE2b-256 6f607a56d668eeab69f2f21fd3fcfb3662b908c81972618a00406b669cbbb5d6

See more details on using hashes here.

File details

Details for the file schema_salad-8.2.20211104054942-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.20211104054942-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm Hash digest
SHA256 c81186628d9a8ac2083568a50405f21a7cf8d57fbdc6d3a25c1bc2a9739cf8ae
MD5 a31c0e7bc20a5ae9896e57c1e3c7ac44
BLAKE2b-256 c4f3a9a24287b09ef3c48c912c24d4bc4c5f7f1f9c79bb3374e2582c46170dac

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