Linked Open Data Modeling Language (LinkML)

Common errors

• ModuleNotFoundError: No module named 'linkml_model'

  cause 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 '...'

  cause 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'

  cause 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.

Warnings

• breaking LinkML 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.
• gotcha The 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.
• gotcha Schema 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.
• gotcha The 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.

Install

• pip install linkml Install core LinkML library

Imports

• SchemaDefinition
  wrong:

  from linkml_model.meta import SchemaDefinition

  correct:

  from linkml_runtime.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

Quickstart

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)