Registry / serialization / linkml

linkml

JSON →
library1.11.1pypypi✓ verified 85d ago

LinkML is a powerful framework for defining data models, particularly for linked open data and semantic web applications. It allows users to define schemas using a YAML-based language, and then generate artifacts such as dataclasses, JSON schemas, ShEx schemas, and more, for various programming languages and data formats. It supports schema validation, data transformation, and integration with existing ontologies. The current version is 1.10.0, and it has an active development and release cadence, with major versions often introducing significant changes.

pip install linkml
INSTALL
IMPORT
SIG · LINKML
L
linkml
serializationpythonv1.11.1
Install
17.6s avg
Import
2468ms
Disk
183MB
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.551s · 178.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 17.6s · import 2.385s · 177MB
183MB installed
● package 183MB
Code
Verified usage

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

SchemaDefinition
from linkml_runtime.linkml_model.meta import SchemaDefinition
from linkml_model.meta import SchemaDefinition
The 'linkml-model' package was deprecated and its functionality absorbed into 'linkml-runtime' from version 1.0.0.
PythonGenerator
from linkml.generators.pythongen import PythonGenerator
YAMLLoader
from linkml_runtime.loaders import YAMLLoader
dump_yaml
from linkml_runtime.utils.datautils import dump_yaml

This quickstart demonstrates how to define a simple LinkML schema as a string, load it, generate Python dataclasses from it, create an instance of a generated class, and then serialize that instance back into YAML. This showcases the core model definition, code generation, and data handling capabilities.

import os from linkml_runtime.linkml_model.meta import SchemaDefinition from linkml.generators.pythongen import PythonGenerator from linkml_runtime.loaders import YAMLLoader from linkml_runtime.utils.datautils import dump_yaml # Define a simple LinkML schema in YAML string schema_content = """ id: http://example.org/my_schema name: my_schema description: A simple LinkML schema example prefixes: ex: http://example.org/my_schema/ default_prefix: ex classes: Person: slots: - id - name - age slots: id: identifier: true range: string name: range: string age: range: integer minimum_value: 0 """ # 1. Load the schema definition loader = YAMLLoader() schema = loader.loads(schema_content, target_class=SchemaDefinition) print(f"Successfully loaded schema: {schema.name}") # 2. Generate Python dataclasses from the schema gen = PythonGenerator(schema=schema) python_code = gen.serialize() # For quickstart, execute generated code in current namespace # In a real application, you'd write this to a file and import it. namespace = {} exec(python_code, namespace) # Get the generated 'Person' class Person = namespace['Person'] # 3. Create an instance of the generated class p = Person(id="P001", name="Alice Smith", age=30) print(f"Created person instance: {p.name}") # 4. Dump the instance to YAML yaml_output = dump_yaml(p) print("\n--- Generated YAML output ---") print(yaml_output)
linkml --version
Debug
Known issues
breakingLinkML underwent a significant rewrite with version 1.0.0. The previous `linkml-model` package was absorbed, and many internal APIs, command-line interface, and generator outputs changed. This is a major breaking change for users upgrading from pre-1.0.0 versions.
fix
Refer to the official LinkML migration guides and release notes for version 1.0.0. Carefully check import paths (e.g., `linkml_runtime` vs `linkml-model`) and update CLI commands.
affects: <1.0.0 to >=1.0.0
gotchaThe separation of `linkml-runtime` and `linkml` can be confusing. `linkml-runtime` contains core metamodel definitions (like `SchemaDefinition`) and utilities (loaders, dumpers, validators), while `linkml` contains generators and the CLI. Incorrect imports are common.
fix
Ensure you are importing from the correct package: `linkml_runtime.linkml_model.meta` for schema definitions and `linkml.generators` for generators, `linkml_runtime.loaders` for loaders, etc.
affects: All versions >=1.0.0
gotchaSchema definition syntax, while generally stable, can have minor evolutions (e.g., new keywords, changes in range handling) between releases. Older schemas might require slight adjustments to work with newer LinkML versions.
fix
Always validate your LinkML schema using `linkml validate your_schema.yaml` after upgrading LinkML. Consult release notes for specific schema syntax changes.
affects: All versions
gotchaThe output of generators (e.g., `PythonGenerator`, `JSONGenerator`) can change across versions, particularly around how inheritance, types, defaults, and prefixes are represented. This can break downstream code or systems that rely on the exact structure of generated artifacts.
fix
Pin your LinkML version if strict consistency of generated output is critical for your project. After upgrading, always regenerate artifacts and perform regression testing on consuming applications.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'linkml_model'
Attempting to import from the deprecated 'linkml-model' package, which was removed in LinkML 1.0.0 and integrated into 'linkml-runtime'.
fix
Update your import statements. For example, `from linkml_model.meta import SchemaDefinition` should become `from linkml_runtime.linkml_model.meta import SchemaDefinition`.
linkml_runtime.utils.validation.ValidationError: Value '...' is not of type '...'
Data being processed does not conform to the types or constraints (e.g., range, minimum_value, pattern) defined in your LinkML schema.
fix
Review your data and the corresponding LinkML schema definition. Ensure data types match the `range` definitions and that values respect any specified constraints. Use `linkml validate` on your data against your schema for detailed error messages.
linkml_runtime.utils.generator.GeneratorException: Cannot find target class for generation: 'MyClassName'
The PythonGenerator (or other generators) cannot locate a class named 'MyClassName' within the loaded schema. This can happen due to typos, incorrect prefix resolution, or if the class is not properly defined.
fix
Verify that 'MyClassName' is correctly spelled and defined in your LinkML schema. Check the schema's `id`, `name`, `prefixes`, and `default_prefix` to ensure correct resolution of class names.
Upgrade
Version history
1.11.1latest on PyPI · released May 20, 2026
Audit
Dependencies
linkml-runtimerequiredProvides core data structures, utilities, and the LinkML metamodel. It is a fundamental dependency for LinkML.
pydanticoptionalUsed by PythonGenerator for generating Pydantic-compatible classes, which offers robust data validation and serialization features.
Agent activity
6 hits · last 30 days
node
6
Resources
linkml — pip install linkml · libregistry