Skip to content

CLI Reference

Complete command-line interface reference for linkml-term-validator.

Overview

linkml-term-validator provides a single command linkml-term-validator with two subcommands:

  • validate-schema - Validate schema permissible values
  • validate-data - Validate data against dynamic enums and bindings

Installation

pip install linkml-term-validator

Or with uv:

uv add linkml-term-validator

Global Options

These options apply to all subcommands:

linkml-term-validator [OPTIONS] COMMAND [ARGS]
Option Description
--help Show help message and exit

validate-schema

Validates that meaning fields in enum permissible values reference valid ontology terms with correct labels.

Syntax

linkml-term-validator validate-schema [OPTIONS] SCHEMA_PATH

Arguments

Argument Type Required Description
SCHEMA_PATH Path Yes Path to LinkML schema file (.yaml)

Options

Option Type Default Description
--config PATH Path None Path to OAK config file (oak_config.yaml) for per-prefix adapter configuration
--adapter TEXT String "sqlite:obo:" Default OAK adapter string (e.g., sqlite:obo:, ols:, bioportal:)
--cache-dir PATH Path cache Directory for caching ontology labels
--no-cache Flag False Disable file-based caching
--strict Flag False Treat warnings as errors
--verbose Flag False Show detailed validation information
--help Flag - Show help message and exit

Examples

Basic validation:

linkml-term-validator validate-schema schema.yaml

With custom config:

linkml-term-validator validate-schema --config oak_config.yaml schema.yaml

Strict mode (warnings become errors):

linkml-term-validator validate-schema --strict schema.yaml

Using OLS instead of SQLite:

linkml-term-validator validate-schema --adapter ols: schema.yaml

Disable caching:

linkml-term-validator validate-schema --no-cache schema.yaml

Verbose output:

linkml-term-validator validate-schema --verbose schema.yaml

Custom cache directory:

linkml-term-validator validate-schema --cache-dir /tmp/ontology-cache schema.yaml

Output

Success (no issues):

✅ Validation passed!

Validation Summary:
  Enums checked: 2
  Permissible values checked: 4
  Meanings validated: 4
  Issues found: 0

Failure (with issues):

❌ ERROR: Label mismatch for GO:0008150
    Enum: BiologicalProcessEnum
    Permissible value: BIOLOGICAL_PROCESS
    Expected label: biological process
    Found label: biological_process

Validation Summary:
  Enums checked: 2
  Permissible values checked: 4
  Meanings validated: 4
  Issues found: 1
    Errors: 1
    Warnings: 0

With unknown prefixes:

✅ Validation passed!

Validation Summary:
  Enums checked: 2
  Permissible values checked: 5
  Meanings validated: 4
  Issues found: 0

⚠️  Unknown prefixes encountered (validation skipped):
  - MY_CUSTOM
  - INTERNAL

Consider adding these to oak_config.yaml to enable validation.

Exit Codes

Code Meaning
0 Success - no validation errors
1 Failure - validation errors found

validate-data

Validates data instances against dynamic enums and binding constraints.

Syntax

linkml-term-validator validate-data [OPTIONS] DATA_PATH

Arguments

Argument Type Required Description
DATA_PATH Path Yes Path to data file (.yaml, .json)

Options

Option Type Default Description
--schema PATH Path Required Path to LinkML schema file
--target-class TEXT String None Target class name to validate against
--config PATH Path None Path to OAK config file
--adapter TEXT String "sqlite:obo:" Default OAK adapter string
--cache-dir PATH Path cache Directory for caching ontology labels
--no-cache Flag False Disable file-based caching
--labels Flag False Validate that labels match ontology canonical labels
--no-dynamic-enums Flag False Skip dynamic enum validation
--no-bindings Flag False Skip binding constraint validation
--verbose Flag False Show detailed validation information
--help Flag - Show help message and exit

Examples

Basic validation:

linkml-term-validator validate-data data.yaml --schema schema.yaml

With target class:

linkml-term-validator validate-data data.yaml --schema schema.yaml --target-class Person

With label validation:

linkml-term-validator validate-data data.yaml --schema schema.yaml --labels

With custom config:

linkml-term-validator validate-data data.yaml \
  --schema schema.yaml \
  --config oak_config.yaml

Only validate bindings (skip dynamic enums):

linkml-term-validator validate-data data.yaml \
  --schema schema.yaml \
  --no-dynamic-enums

Only validate dynamic enums (skip bindings):

linkml-term-validator validate-data data.yaml \
  --schema schema.yaml \
  --no-bindings

Full validation with all options:

linkml-term-validator validate-data data.yaml \
  --schema schema.yaml \
  --target-class GeneAnnotation \
  --config oak_config.yaml \
  --cache-dir cache \
  --labels \
  --verbose

Output

Success (no issues):

✅ Validation passed!

Validation Summary:
  Dynamic enums validated: 5
  Bindings validated: 3
  Issues found: 0

Failure (dynamic enum violation):

❌ ERROR: Value 'GO:0005575' does not satisfy dynamic enum constraint
    Class: GeneAnnotation
    Slot: go_term.id
    Enum: BiologicalProcessEnum
    Expected: Descendant of GO:0008150 (biological_process)
    Found: GO:0005575 (cellular_component)

Validation Summary:
  Dynamic enums validated: 5
  Bindings validated: 3
  Issues found: 1
    Errors: 1

Failure (label mismatch with --labels):

❌ ERROR: Label mismatch for GO:0007049
    Class: GeneAnnotation
    Slot: go_term.label
    Expected label: cell cycle
    Found label: cell-division cycle

Validation Summary:
  Dynamic enums validated: 5
  Bindings validated: 3
  Label validations: 3
  Issues found: 1
    Errors: 1

Exit Codes

Code Meaning
0 Success - no validation errors
1 Failure - validation errors found

Common Workflows

CI/CD Validation

Schema validation in CI:

#!/bin/bash
set -e  # Exit on error

echo "Validating LinkML schemas..."
linkml-term-validator validate-schema \
  --strict \
  --config oak_config.yaml \
  --cache-dir cache \
  src/schema/main.yaml

echo "✅ Schema validation passed"

Data validation in CI:

#!/bin/bash
set -e

echo "Validating curated data..."
linkml-term-validator validate-data \
  data/curated/*.yaml \
  --schema src/schema/main.yaml \
  --config oak_config.yaml \
  --labels \
  --cache-dir cache

echo "✅ Data validation passed"

Local Development

Quick schema check:

linkml-term-validator validate-schema schema.yaml

Validate with fresh cache:

rm -rf cache/
linkml-term-validator validate-schema schema.yaml

Test with OLS (no local downloads):

linkml-term-validator validate-schema --adapter ols: --no-cache schema.yaml

Debugging

Verbose output:

linkml-term-validator validate-schema --verbose schema.yaml

Check specific data file:

linkml-term-validator validate-data \
  data/problematic.yaml \
  --schema schema.yaml \
  --verbose

Configuration Files

oak_config.yaml

Controls which ontology adapters to use for different prefixes:

ontology_adapters:
  GO: sqlite:obo:go
  CHEBI: sqlite:obo:chebi
  UBERON: sqlite:obo:uberon

  # Skip validation
  linkml: ""
  schema: ""

Use with:

linkml-term-validator validate-schema --config oak_config.yaml schema.yaml

See Configuration for details.

Shell Completion

Bash

# Add to ~/.bashrc
eval "$(_LINKML_TERM_VALIDATOR_COMPLETE=bash_source linkml-term-validator)"

Zsh

# Add to ~/.zshrc
eval "$(_LINKML_TERM_VALIDATOR_COMPLETE=zsh_source linkml-term-validator)"

Fish

# Add to ~/.config/fish/config.fish
_LINKML_TERM_VALIDATOR_COMPLETE=fish_source linkml-term-validator | source

Environment Variables

Variable Description Default
BIOPORTAL_API_KEY API key for BioPortal adapter None
OAK_CACHE_DIR Default cache directory for OAK ~/.data/oaklib

Troubleshooting

Command not found

Problem:

linkml-term-validator: command not found

Solution: Ensure the package is installed and your PATH is configured:

pip install linkml-term-validator
which linkml-term-validator

Unknown prefixes

Problem:

⚠️  Unknown prefixes encountered (validation skipped):
  - MY_ONTOLOGY

Solution: Add the prefix to your oak_config.yaml:

ontology_adapters:
  MY_ONTOLOGY: sqlite:obo:my_ontology

Or use a local OBO file:

ontology_adapters:
  MY_ONTOLOGY: simpleobo:path/to/ontology.obo

Slow validation

Problem: Validation takes a long time on first run.

Solution: This is expected when using sqlite:obo: adapter for the first time. OAK is downloading and building the ontology database. Subsequent runs will be fast due to caching.

To speed up development: - Use simpleobo: adapter with local OBO files for testing - Cache the cache/ directory in CI/CD - Use ols: adapter to avoid local downloads (slower per query but no initial download)

Stale cache

Problem: Validation shows old labels even though ontology has been updated.

Solution: Clear the cache:

rm -rf cache/
linkml-term-validator validate-schema schema.yaml

Or disable caching:

linkml-term-validator validate-schema --no-cache schema.yaml

See Also