When authoring a schema – especially when it is large or there are many authors – it is important to establish and adhere to best practices. For example, while providing a description for each schema element is not required, descriptions can help reduce miscommunication between schema authors. LinkML provides a configurable linter to identify violations of best practices or error-prone patterns.
linkml-lint command performs checks on a schema which – while valid – may not represent best practices or may indicate a likely mistake in the schema. These checks are referred to as rules and without additional configuration a default set of rules will be used.
To lint a single schema file:
To recursively lint a directory of schema files:
linkml-lint command can be configured with a YAML configuration file. The configuration file can be provided using the
--config command line option:
linkml-lint --config myconfig.yaml myschema.yaml
Alternatively, if there is a file named
.linkmllint.yaml in the current working directory when you run
linkml-lint that file will automatically be loaded as the configuration file. If all or most of the schema files in a project can be checked with the same rules, storing the configuration at the root of the project in a
.linkmllint.yaml file can make it more convenient to check them without having to pass the
Here is an example of a configuration file which includes all the recommended rules and enables an additional rule named
# Use all the recommended rules and also enable the no_empty_title rule extends: recommended rules: no_empty_title: level: error
extends field of the configuration file allows you to inherit from an existing configuration. Currently the only valid value for this field is
rules field is a dictionary where each key is a rule name and the value is the configuration for that rule. Every rule has at least one configurable property:
level. Each rule’s
level can be set to
disabled (the default) meaning the schema will not be checked with that rule, or
level can be set to
error. If set to
error the schema will be checked with that rule and violations will be reported. The distinction between
error is solely cosmetic and is designed to help you prioritize issues to fix. If you are unsure there is no harm in only using the
error level. Some rules have additional configuration beyond the
level property, as described in the Rules section.
To use the recommended configuration set except for one of the rules, manually specify
level: disabled for that rule:
# Use the recommended rule set except for the standard_naming rule extends: recommended rules: standard_naming: level: disabled
It is also acceptable to not extend the recommended set. Simply omit the
extends field from your configuration. In that case, only the rules that your configuration enables are checked:
# Only the no_empty_title and standard_naming rules will be checked rules: no_empty_title: level: error standard_naming: level: error
Rule names denoted with a star ⭐ are part of the
recommended configuration set.
Enforce canonical prefixes by verifying that the mappings defined in the schema’s
prefixes slot agree with those provided by the prefixmaps package.
prefixmaps_contexts: The list of context names which will be loaded by the
prefixmapslibrary to do the validation. The order of names is meaningful and will be preserved. See also: prefixmaps documentation. Default:
Disallow empty titles on schema elements.
slot_usage definitions where the name of the slot does not refer to an existing slot of the class.
Disallow use of
uri: xsd:int in type definitions. In nearly all cases,
xsd:integer should be used instead.
Enforce consistent formatting of enum permissible values. This rule may conflict with the
standard_naming rule, but it is more flexible.
format: The enforced format of enum permissible values. Special values “snake”, “uppersnake”, “camel”, and “kebab” will be recognized, otherwise the value will be interpreted as a regular expression. Default:
Require any slot in the metamodel with
recommended: true (e.g.
description) to be provided.
include: If specified, only elements with the provided names will be checked. Default:
exclude: All elements except the ones with names specified in this list will be checked. Default:
Enforce standard naming conventions: CamelCase for classes, snake_case for slots, CamelCase for enums, snake_case (default) or UPPER_SNAKE for permissible_values (see
permissible_values_upper_case option). This rule may conflict with the
true, permissible values will be checked for UPPER_SNAKE, otherwise snake_case. Default:
Require a single class with
tree_root: true and optionally verify that class’s name.
true, in addition to validating that a
tree_root: trueClassDefinition exists, the rule will also validate that is has the name provided by the
root_class_name: The name of the root class. Default:
By default, if the
linkml-lint command identifies violations of the configured rules it will print the files and issues to the terminal. This behavior can be changed with the
--output command line options.
The valid values for
--format are terminal (the default), markdown, json, and tsv.
--output option is provided the report will be written to the specified file instead of the terminal.
For example, to generate a markdown report in a file named
linkml-lint --format markdown --output linter-results.md myschema.yaml
If the linter does not encounter any rule violations at all it will exit with code
If the linter encounters rule violations with
level: error it will exit with code
2. This will be the case regardless of whether there are also rule violations with
By default, if the linter encounters only rule violations with
level: warning it will exit with code
1. This behavior can be changed with command line options. In this scenario, if the
--ignore-warnings flag is provided the exit code will be
0. If instead the
--max-warnings <int> option is passed, the exit code will be
0 depending on whether the number of warning rule violations is greater than the provided number or not. If both
--max-warnings are used
--ignore-warnings takes precedence.