LinkML Runtime

Common errors

• ImportError: cannot import name 'BaseModel' from 'pydantic.main' (C:\Users\...\site-packages\pydantic\main.py)

  cause You are using `linkml-runtime>=1.0.0` with an older Pydantic V1 installation (`pydantic<2.0.0`).
  fix Upgrade Pydantic to version 2 or newer: `pip install 'pydantic>=2.0.0'`

• ValidationError: 1 validation error for Person\nname\n  field required (type=value_error.missing)

  cause The data being converted is missing a required field, or a field has an invalid type/value according to the LinkML schema's rules (e.g., `required: true`, `minimum_value`, `pattern`).
  fix Inspect your input data and the corresponding LinkML schema definition. Ensure all `required` slots are present and values conform to `range` and other constraints.

• FileNotFoundError: [Errno 2] No such file or directory: 'my_schema.yaml'

  cause The path provided to `SchemaView` or loaders (e.g., `YAML_LOADER.load()`) for your LinkML schema file is incorrect or the file does not exist at that location.
  fix Verify the file path. Use an absolute path or ensure the relative path is correct from where your script is executed. Check for typos in the filename.

Warnings

• breaking LinkML Runtime versions 1.0.0 and above require Pydantic V2. If your project uses Pydantic V1, installing `linkml-runtime>=1.0.0` will lead to `ImportError` or `ValidationError` incompatibilities.
  Fix: Upgrade your project's Pydantic dependency to `pydantic>=2.0.0` or use an older `linkml-runtime` version (pre-1.0.0) if Pydantic V1 is strictly required by other dependencies.
• gotcha Errors in LinkML schema definition (YAML/JSON syntax, incorrect LinkML elements) can result in obscure `jsonschema` or `Pydantic` errors during schema loading or when generating models. These can be hard to debug without careful inspection of the schema structure.
  Fix: Validate your LinkML schema using the `linkml-validate` command-line tool (from `linkml`) or a dedicated LinkML IDE/linter before attempting to load it programmatically. Ensure all class, slot, and type definitions are correctly formatted and referenced.
• gotcha By default, `dict_to_object` can sometimes be more permissive than anticipated, silently ignoring extra fields or performing type coercion. For stricter validation, ensure your schema explicitly defines all expected fields and types.
  Fix: For very strict validation, you might need to combine `dict_to_object` with an explicit validation step or directly use the Pydantic models generated by `linkml-generator` for your schema, which offer more granular control over validation behavior (e.g., `extra='forbid'`).

Install

• pip install linkml-runtime Install latest version

Imports

• SchemaView

  from linkml_runtime.utils.schemaview import SchemaView

• YAML_LOADER

  from linkml_runtime.loaders.yaml_loader import YAML_LOADER

• JSON_LOADER

  from linkml_runtime.loaders.json_loader import JSON_LOADER

• dict_to_object

  from linkml_runtime.utils.dictutils import dict_to_object

• object_to_dict

  from linkml_runtime.utils.dictutils import object_to_dict

• SchemaDefinition
  wrong:

  from linkml_runtime.linkml_model import SchemaDefinition

  correct:

  from linkml_runtime.linkml_model.meta import SchemaDefinition

  Core LinkML metaclasses are nested under the 'meta' module.

Quickstart

This quickstart demonstrates how to load a LinkML schema from a YAML string using `SchemaView`, convert a Python dictionary into a schema-compliant object using `dict_to_object`, access its attributes, and handle validation errors. It also shows how to convert an object back to a dictionary.

import os
from linkml_runtime.utils.schemaview import SchemaView
from linkml_runtime.utils.dictutils import dict_to_object, object_to_dict

# 1. Define a simple LinkML schema (YAML string)
schema_yaml = """
id: https://example.org/my_data_model
name: my_data_model
prefixes:
  ex: https://example.org/my_data_model/
default_prefix: ex

classes:
  Person:
    slots:
      - id
      - name
      - age
    required:
      - id
      - name
  
slots:
  id:
    range: string
    identifier: true
  name:
    range: string
  age:
    range: integer
    minimum_value: 0
"""

# 2. Load the schema into a SchemaView object
schema_view = SchemaView(schema_yaml)

# 3. Define a simple data instance (Python dictionary)
person_data = {
    "id": "P001",
    "name": "Alice Wonderland",
    "age": 30
}

# 4. Convert the dictionary data to a Python object based on the schema
# `dict_to_object` uses the schema definition to instantiate a Pydantic-backed object.
person_object = dict_to_object(person_data, target_class=schema_view.get_class("Person"), schemaview=schema_view)

print(f"Original dict: {person_data}")
print(f"Converted object: {person_object}")
print(f"Object ID: {person_object.id}")
print(f"Object Name: {person_object.name}")

# Demonstrate implicit validation (attempting to convert invalid data)
invalid_person_data = {
    "id": "P002",
    "name": None, # 'name' is required and cannot be None
    "age": -5     # 'age' must be non-negative
}

try:
    print("\nAttempting to convert invalid data...")
    dict_to_object(invalid_person_data, target_class=schema_view.get_class("Person"), schemaview=schema_view)
except Exception as e:
    print(f"Caught expected validation error: {e.__class__.__name__}: {e}")

# 5. Convert the object back to a dictionary
converted_back_dict = object_to_dict(person_object, schemaview=schema_view)
print(f"\nObject converted back to dict: {converted_back_dict}")