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 uv to manage the python environment and dependencies.

See the uv docs for uv installation instructions.

Install the project dependencies and create a virtual environment:

uv sync

Run tests or other scripts:

uv run <command>
uv run pytest tests/

Useful commands

These assume that you have already run uv sync to install the credit engine virtual environment and dependencies.

generate derived files in all formats:

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

lint the KBase linkml schema file:

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

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

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

generate JSONschema version:

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

generate Python classes:

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

generate Pydantic classes:

uv run 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):

uv run 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):

uv run 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