KBase Credit Engine

This repo holds the schema and associated scripts used by the KBase Credit Engine.

The KBase Credit Engine is a project aimed at ensuring that appropriate citation information exists for data entering and/or produced by the KBase software and data science platform to allow credit to be attributed to those who produced the data.

• KBase Credit Engine
  • Metadata Schema
    • Schema Diagram
  • Software Installation
    • Useful commands
      • JSONschema data validation

Metadata Schema

The KBase credit metadata schema is maintained in linkml format; other formats (including the python class) can be generated from the linkml schema file.

See the linkml documentation for full details on using the linkml format and the related tools.

Full schema documentation can be found at https://kbase.github.io/credit_engine/.

Schema Diagram

Generated from the Pydantic version of the KBase Citation Metadata Schema using erdantic.

See below for how to regenerate the ER diagram after making changes to the schema.

Software Installation

This repo uses poetry to manage the python environment and dependencies.

See the poetry docs for poetry installation instructions.

Install the project dependencies and create a virtual environment:

poetry install

Activate the virtual environment:

poetry shell

Run tests or other scripts:

poetry run <command>
poetry run pytest tests/

Useful commands

These assume that you have already run poetry shell to activate the credit engine virtual environment.

generate derived files in all formats:

gen-project -d schema/kbase/ schema/kbase/linkml/credit_metadata.yaml

lint the KBase linkml schema file:

linkml-lint -f terminal schema/kbase/linkml/credit_metadata.yaml

validate data (in file data.yaml) against the schema:

linkml-validate -s schema/kbase/linkml/credit_metadata.yaml data.yaml

generate JSONschema version:

gen-json-schema schema/kbase/linkml/credit_metadata.yaml > schema/kbase/jsonschema/credit_metadata.schema.json

generate Python classes:

gen-python schema/kbase/linkml/credit_metadata.yaml > schema/kbase/python/credit_metadata.py

generate Pydantic classes:

gen-pydantic schema/kbase/linkml/credit_metadata.yaml > schema/kbase/python/credit_metadata_pydantic.py

generate an ER diagram from the Pydantic classes using erdantic (assumes that erdantic has been installed already):

erdantic schema.kbase.python.credit_metadata_pydantic.CreditMetadata -o schema/kbase/kbase-schema.png

generate a YUML schema diagram (can be visualised at yuml.me):

gen-yuml schema/kbase/linkml/credit_metadata.yaml

JSONschema data validation

install the JSONschema check script:

brew install check-jsonschema

To test a file or files against the schema, use the command:

check-jsonschema --schemafile schema/kbase/jsonschema/credit_metadata.schema.json data_file_1.json data_file_2.json

or

check-jsonschema --schemafile schema/kbase/jsonschema/credit_metadata.schema.json sample_data/**/*kbcms.json