LinkML Tutorial 1: Introduction to LinkML

This is a repository that walks through the LinkML modeling language, helpful LinkML command line tools, and automatic schema documentation generation. The main branch of this repository has the resulting structure of a LinkML project that follows the tutorial to its completion. If you want to walk through the tutorial step by step, or refer back to a section of the tutorial at a later time, you can check out the stepped branches as needed.

For example, if you wanted to see the schema and infrastructure as it looks before implementing enumerations, you could refer to the step_5_validation branch.

For reference, the available sections are:

Section 1: Setting up a LinkML project from scratch

NOTE: this section is currently out of date. It needs to be revised to talk about copier rather than cookiecutter.

• step_0_basic_project_creation

Section 2: Developing a model, validating the model with test data

• step_1_model_components
• step_2_classes_and_slots
• step_3_hierarchies
• step_4_mappings_and_uris
• step_5_validation
• step_6_enumerations

Section 3: Checking the model for best practices (linting)

• step_7_linting

Section 4: Generating model documentation

• step_8_documentation

Section 5: Schemasheets

• step_9_schemasheets

Website

• https://linkml.github.io/linkml-tutorial

Repository Structure

• src/data/examples/ - example data
• project/ - project files (do not edit these)
• src/ - source files (edit these)
  • linkml_tutorial
    • schema -- LinkML schema (edit this)
• datamodel -- Generated python datamodel
• tests - python tests

Developer Documentation

Use the make command to generate project artifacts:

• make all: make everything
• make deploy: deploys site

To validate, create a poetry virtual environment, install the dependencies of this tutorial, and then run the tests and/or linkml-validate.

NOTE: we have switched to using uv rather than poetry (but poetry may still work).

poetry install
poetry run linkml-validate -s src/linkml_tutorial/schema/linkml_tutorial.yaml src/data/examples/Person-001.yaml --target-class PersonCollection
poetry run linkml-validate -s src/linkml_tutorial/schema/linkml_tutorial.yaml src/data/examples/Animal-001.yaml --target-class AnimalCollection

make test

To generate documentation locally (requires mkdocs):

make testdoc

and navigate to http://127.0.0.1:8000/linkml-tutorial/

To convert the test data from YAML to JSON, run:

poetry run linkml-convert -s src/linkml_tutorial/schema/linkml_tutorial.yaml -t json src/data/examples/Animal-001.yaml --target-class AnimalCollection
poetry run linkml-convert -s src/linkml_tutorial/schema/linkml_tutorial.yaml -t json src/data/examples/Person-001.yaml --target-class PersonCollection

To convert the test data from YAML to RDF, run:

poetry run linkml-convert -s src/linkml_tutorial/schema/linkml_tutorial.yaml -t rdf src/data/examples/Animal-001.yaml --target-class AnimalCollection
poetry run linkml-convert -s src/linkml_tutorial/schema/linkml_tutorial.yaml -t rdf src/data/examples/Person-001.yaml --target-class PersonCollection

To compile changed schemasheets, run:

make compile-sheets

For more information, please consult the online LinkML tutorial A link to a video tutorial is coming soon!

Credits

This project was made with linkml-project-cookiecutter (but we have now switched to recommending linkml-project-copier for setting up a new LinkML project).