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.8+ 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

Codegen Examples

These are helpful to see how to use the output of schema-salad-tool –codegen in different languages for loading and/or creating/editing/saving objects, using the CWL v1.2 schema as an example.

Language

Repository

Serialization Example | Deserialization Example

Python

https://github.com/common-workflow-language/cwl-utils/

create_cwl_from_objects.py

load_document()

Java

https://github.com/common-workflow-language/cwljava/

(Not yet implemented)

PackedWorkflowClassTest.java

TypeScript

https://github.com/common-workflow-lab/cwl-ts-auto

Creating, editing, and saving CWL docs with TypeScript

Loading CWL documents with TypeScript

.Net

https://github.com/common-workflow-lab/CWLDotNet

Creating, editing, and saving CWL docs with .Net

Loading CWL documents with .Net

C++

https://github.com/common-workflow-lab/cwl-cpp-auto

cwl_output_example.cpp

(Not yet implemented)

D

https://github.com/common-workflow-lab/cwl-d-auto

How to use

How to use

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

Uploaded Source

Built Distributions

schema_salad-8.4.20230927144413-py3-none-any.whl (600.0 kB view details)

Uploaded Python 3

schema_salad-8.4.20230927144413-cp311-cp311-musllinux_1_1_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.11 musllinux: musl 1.1+ ARM64

schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64

schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.28+ ARM64

schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.24+ ARM64

schema_salad-8.4.20230927144413-cp310-cp310-musllinux_1_1_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.10 musllinux: musl 1.1+ ARM64

schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ ARM64

schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.28+ ARM64

schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.24+ ARM64

schema_salad-8.4.20230927144413-cp39-cp39-musllinux_1_1_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.9 musllinux: musl 1.1+ ARM64

schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ ARM64

schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.28+ ARM64

schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.24+ ARM64

schema_salad-8.4.20230927144413-cp38-cp38-musllinux_1_1_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.8 musllinux: musl 1.1+ ARM64

schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.17+ ARM64

schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.28+ ARM64

schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.8 manylinux: glibc 2.17+ ARM64 manylinux: glibc 2.24+ ARM64

File details

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

File metadata

File hashes

Hashes for schema-salad-8.4.20230927144413.tar.gz
Algorithm Hash digest
SHA256 2018cca36ed29c304010fd89daf2f8e42ba7257efb4447af17bfb6cc59a81534
MD5 a6ca2413c24702c175e2dc56ea3b7d29
BLAKE2b-256 5882350aab56ffd3ad7e2d285be889ca5c68f9ce5dd58eb7dd5be39dcbd93bbd

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-py3-none-any.whl
Algorithm Hash digest
SHA256 e127948ed425e1e5fd38cb8beeeca49a6aaa5f48cc3cd13aaf948372eac1e545
MD5 6f2de346b24c1972138217c08acff458
BLAKE2b-256 e555c9ffb1b9cd1b4e641bb6db5f2a1f5208b79c59e9d9813739ee649feda9a4

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp311-cp311-musllinux_1_1_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp311-cp311-musllinux_1_1_aarch64.whl
Algorithm Hash digest
SHA256 4068b52c0815db16e0d93c190df64fef6141c0d77667f27e3479a2be4e115d05
MD5 ed6926e17262378ee7ee624ed4c5aafb
BLAKE2b-256 40349dd4fb36aab573b5b61a8945478013c7bf9983e7802ca9d08fc882beff2e

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 986be2894e2742daffc8bc0d7816e3ac1faced52a67b1d55f541ed939a267c6d
MD5 a88b4a06c70488d87c3defa9ea39acc3
BLAKE2b-256 981490265e3a359791505c1fd87bfc4250ce83879d22dc551684ea7a9c973428

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6a5ff036270bdd3a27095923b44f797872571b747df7b2f89bec28fe59be93b7
MD5 8e01811e8cc7c047ac9b7f4a74522839
BLAKE2b-256 bfcd1adccb963274e19c54fd3af025aa54e27fb347756c6cd4b0150a996ddee1

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl
Algorithm Hash digest
SHA256 e47a8ca8913ae28eaab1e5528c53350139c215a28189f42a9f0375f5c40aa1ba
MD5 58c45f0ea6ad3f5bb904e21820e542a7
BLAKE2b-256 8ed4760f876336c5f2d5ac5b6bf7e2209bd7f327bcbf95a959e9d5baadfff825

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp310-cp310-musllinux_1_1_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp310-cp310-musllinux_1_1_aarch64.whl
Algorithm Hash digest
SHA256 055e241bc2f1f5ea68f9898be384558abf5f83ae5755c155c9a70eab3abd876d
MD5 8009fd56e208926df493f85e40db6470
BLAKE2b-256 c45ab80d301ce8c4ee93c2a9f4536a1046c3e4b56a6146328f301037334746c1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 4bd7b860bfdb0bd776a50d505ad682c0edaa8e4c72ec2454c15567428d0cd452
MD5 b86741bc17f4f0cd098b0f38cea70cf0
BLAKE2b-256 2c1ea85efb3fcd5dd5f39bcca88325d45506077896fa7515a3fe8a2c6c77ca00

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 94b5489917277bf77b96963dfde8e2fec3a534c2542f63de1bba881177cfe8bb
MD5 21017c24e8207a3743a8152d1a7104d3
BLAKE2b-256 a3f6ff4b973edc24a64226d2579c1f1638022c4bea6e7e702301f6704e6eb090

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl
Algorithm Hash digest
SHA256 724aeaae7d90715565cd8b4cde9e89aa8bd8d91bd4b4e9da82f693b7b0494a8d
MD5 f1ad7419a47ea7355e9e60b80ad191a1
BLAKE2b-256 71b08ca4986789c8fb21c1de0090d087a278c6ca96d838a4ca7180c0c7ba0d4f

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp39-cp39-musllinux_1_1_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp39-cp39-musllinux_1_1_aarch64.whl
Algorithm Hash digest
SHA256 2d83fbed1a91c5336b4b6f10a2a8e47fb14a3bcad01298b000a30471fb26fc8d
MD5 7f5416c7fcdafa47984d36e77b0601dd
BLAKE2b-256 013a7946897b3b65ac6257fcb0130570a927524b005ec4daa52b4670b95d1111

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 66d89fa772c6e28910841f575c7a08b5dde05b42feaea0ec712a6aaef70de891
MD5 a16cde83af6d38711ef0ebae6a77fd5f
BLAKE2b-256 bf0f6bf2b402a05669faf0bf108c7cfccc2b7f5ade95abf2df40cd2c16f5b669

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 e50f1bb7d1faf78f3e163045c3e7039304a2fcf2b3399f5bc4b9807f7a867157
MD5 3d9b969b3466e4eed308e78e4100a25f
BLAKE2b-256 3ce289d15d5ec70397bbb129677c204c3e23457486aa46aebf6eaab198add27e

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl
Algorithm Hash digest
SHA256 8d14ca519177a07c4253990b89847b88fa53bb4015a7bd1b7b0aac5593ec00a9
MD5 76bd0c0500287a7654725a5f5dd6be73
BLAKE2b-256 7491015842ab16c53c321374341626fe313a158d9a2010ad79dc3d5e3acfedfe

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp38-cp38-musllinux_1_1_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp38-cp38-musllinux_1_1_aarch64.whl
Algorithm Hash digest
SHA256 d10739ce7d41f592fdc0a5eea1e2e46edba5d07dc768513a058c4ce237edb3ce
MD5 5e7d7c108e9bc34363f87a2f3301ed02
BLAKE2b-256 92988756d5e406268b7b6371871dda68f678bb43ca765c9ecea87483e06a8da3

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a598d69feb226919e80e6f016f543c7e1f534bf516ededd943290fd961c9e6c2
MD5 645df78faa7130f44b592e1abe539661
BLAKE2b-256 13e2334a7dc99173df7bdc379ce2af8ca0f20fca8aece3eb90aef338bdc8401e

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 bc5cdc0341b94b5aeb2e34dfae3e47df347a45b9bb07b09f12422fe85186de16
MD5 f881c74a84bef57cf04635a6e1da2190
BLAKE2b-256 ab2f6b7afccde8239c7058314978c9434e5a16744892b9cbba86a0172a5c3671

See more details on using hashes here.

File details

Details for the file schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl.

File metadata

File hashes

Hashes for schema_salad-8.4.20230927144413-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl
Algorithm Hash digest
SHA256 ca6652c369e398836ecfe353afa57355e81023cd87132e9fd97ee7950e5a698a
MD5 28b4dc62637f0c09d4633fa4b1a78ef6
BLAKE2b-256 bfb9a4fe6a2a237569a96394287368fb50a97882b53599b5f14c65371f46c2b3

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