Registry / serialization / linkml-runtime

linkml-runtime

JSON →
library1.11.1pypypi✓ verified 85d ago

LinkML Runtime is the core Python runtime environment for LinkML, the Linked open data modeling language. It provides essential functionality for working with LinkML schemas, including schema loading, data validation, serialization, and deserialization. The current version is 1.10.0, and it maintains a close release cadence with the broader LinkML ecosystem, typically featuring bug fixes and enhancements aligned with LinkML core developments.

pip install linkml-runtime
INSTALL
IMPORT
SIG · LINKML-RUNTIME
L
linkml-runtime
serializationpythonv1.11.1
Install
8.9s avg
Import
2397ms
Disk
73MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.11.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 2.477s · 74.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 8.9s · import 2.316s · 74MB
73MB installed
● package 73MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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
from linkml_runtime.linkml_model.meta import SchemaDefinition
from linkml_runtime.linkml_model import SchemaDefinition
Core LinkML metaclasses are nested under the 'meta' module.

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}")
linkml --version
Debug
Known issues
breakingLinkML 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.
affects: >=1.0.0
gotchaErrors 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.
affects: all
gotchaBy 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'`).
affects: all
Errors
Common errors & fixes
ImportError: cannot import name 'BaseModel' from 'pydantic.main' (C:\Users\...\site-packages\pydantic\main.py)
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)
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'
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.
Upgrade
Version history
1.11.1latest on PyPI · released May 20, 2026
Audit
Dependencies
pydantic>=2.0.0requiredCore dependency for data modeling and validation; LinkML Runtime relies heavily on Pydantic models for its internal operations and generated classes. Version 2.x is required for linkml-runtime 1.x.
Agent activity
4 hits · last 30 days
node
4
Resources
linkml-runtime — pip install linkml-runtime · libregistry