Validation Rules

Validator Classes

class sloth.mmcif.rules.DictionaryValidator

Bases: ValidatorPlugin

Validator auto-generated from an mmCIF dictionary.

Parses a .dic file via SLOTH’s DictionaryParser, retains the schema metadata, and registers validators from it:

• mandatory items — from _item.mandatory_code

• enumeration — from _item_enumeration.value

• type regex — from _item_type_list.construct

• foreign-key integrity — single-key relationships

• composite-key integrity — multi-key relationships

• parent/child category presence — parent must exist when child does

Parameters:

• dict_path (str, optional) – Path to an mmCIF dictionary. Defaults to the bundled mmcif_pdbx_v50.dic.

• quiet (bool) – Suppress progress messages from the dictionary parser (default True).

• Usage:: –

  from sloth.mmcif.rules import DictionaryValidator

  v = DictionaryValidator() # schema-only rules handler.register(“validate”, v)

__init__(dict_path=None, *, quiet=True)

Parameters:

• dict_path (str | None)

• quiet (bool)

class sloth.mmcif.rules.MmcifValidator

Bases: DictionaryValidator

Full wwPDB validator = dictionary schema + deposition business rules.

Inherits all schema-level checks from DictionaryValidator, then registers wwPDB-specific rules from the declarative tables below.

Parameters:

• dict_path (str, optional) – Path to an mmCIF dictionary. Defaults to the bundled mmcif_pdbx_v50.dic.

• quiet (bool) – Suppress dictionary parser progress messages (default True).

• Usage:: –

  from sloth.mmcif.rules import MmcifValidator

  v = MmcifValidator() # full wwPDB + dictionary rules handler.register(“validate”, v)

__init__(dict_path=None, *, quiet=True)

Parameters:

• dict_path (str | None)

• quiet (bool)

Single-Category Rule Factories

sloth.mmcif.rules.mandatory_items(items, exclude=(), severity=ValidationSeverity.ERROR)

Items that must be non-null when the category is present.

Return type:

Callable[[Category], None]

Parameters:

• items (Sequence[str])

• exclude (Sequence[str])

• severity (ValidationSeverity)

sloth.mmcif.rules.one_of_following(items, severity=ValidationSeverity.ERROR)

At least one of items must be non-null.

Return type:

Callable[[Category], None]

Parameters:

• items (Sequence[str])

• severity (ValidationSeverity)

sloth.mmcif.rules.value_length(item, min_len=None, max_len=None, severity=ValidationSeverity.WARNING)

String length bounds for an item.

Return type:

Callable[[Category], None]

Parameters:

• item (str)

• min_len (int | None)

• max_len (int | None)

• severity (ValidationSeverity)

sloth.mmcif.rules.value_range(item, min_val=None, max_val=None, severity=ValidationSeverity.WARNING)

Numeric bounds for an item.

Return type:

Callable[[Category], None]

Parameters:

• item (str)

• min_val (float | None)

• max_val (float | None)

• severity (ValidationSeverity)

sloth.mmcif.rules.conditional_mandatory(required_items, when_item, when_values, severity=ValidationSeverity.ERROR)

Items that must be non-null when when_item has one of when_values.

Return type:

Callable[[Category], None]

Parameters:

• required_items (Sequence[str])

• when_item (str)

• when_values (Sequence[str])

• severity (ValidationSeverity)

sloth.mmcif.rules.regex_check(item, pattern, error_text='', severity=ValidationSeverity.ERROR)

Values of item must match pattern.

Return type:

Callable[[Category], None]

Parameters:

• item (str)

• pattern (str)

• error_text (str)

• severity (ValidationSeverity)

sloth.mmcif.rules.ordering_check(item_a, item_b, op='<', severity=ValidationSeverity.WARNING)

Numeric ordering: item_a op item_b (per row).

Parameters:

• op (str) – One of "<", "<=", ">", ">=".

• item_a (str)

• item_b (str)

• severity (ValidationSeverity)

Return type:

Callable[[Category], None]

sloth.mmcif.rules.allowed_pairs(item_a, item_b, valid_mapping, severity=ValidationSeverity.ERROR)

Restrict allowed (item_a, item_b) value combinations per row.

valid_mapping maps each value of item_a to the sequence of allowed values in item_b.

Return type:

Callable[[Category], None]

Parameters:

• item_a (str)

• item_b (str)

• valid_mapping (Mapping[str, Sequence[str]])

• severity (ValidationSeverity)

sloth.mmcif.rules.min_rows(n, severity=ValidationSeverity.ERROR)

Category must contain at least n rows.

Return type:

Callable[[Category], None]

Parameters:

• n (int)

• severity (ValidationSeverity)

sloth.mmcif.rules.enumeration_check(item, allowed_values, severity=ValidationSeverity.ERROR)

Values of item must be in allowed_values.

Mirrors the dictionary _item_enumeration validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category], None]

Parameters:

• item (str)

• allowed_values (Sequence[str])

• severity (ValidationSeverity)

sloth.mmcif.rules.type_check(item, type_pattern, type_name='', severity=ValidationSeverity.ERROR)

Values of item must match the data-type regex type_pattern.

Mirrors the dictionary _item_type_list.construct validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category], None]

Parameters:

• item (str)

• type_pattern (str)

• type_name (str)

• severity (ValidationSeverity)

Cross-Category Rule Factories

sloth.mmcif.rules.foreign_key(child_item, parent_item, severity=ValidationSeverity.ERROR)

Cross-checker: every non-null value of child_item in cat_a must exist in parent_item of cat_b.

Mirrors the FK integrity check from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

• child_item (str)

• parent_item (str)

• severity (ValidationSeverity)

sloth.mmcif.rules.parent_child(severity=ValidationSeverity.ERROR)

Cross-checker: if child category (cat_a) is present, parent category (cat_b) must also be present and non-empty.

Mirrors the parent/child category validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

severity (ValidationSeverity)

sloth.mmcif.rules.composite_key(child_items, parent_items, severity=ValidationSeverity.ERROR)

Cross-checker: each combination of child_items in cat_a must exist as a matching combination of parent_items in cat_b.

Mirrors the composite key validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

• child_items (Sequence[str])

• parent_items (Sequence[str])

• severity (ValidationSeverity)

sloth.mmcif.rules.oper_expression(expression_item='oper_expression', oper_list_item='id', severity=ValidationSeverity.ERROR)

Cross-checker: validate that operation expression references in cat_a all resolve to valid IDs in cat_b (_pdbx_struct_oper_list).

Parses expressions like (1-60), (1,2,5), (X0)(1-5,11-15).

Mirrors the oper_expression validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

• expression_item (str)

• oper_list_item (str)

• severity (ValidationSeverity)

sloth.mmcif.rules.cross_mandatory(required_items, severity=ValidationSeverity.ERROR)

Cross-checker: required_items must exist in the second category.

Return type:

Callable[[Category, Category], None]

Parameters:

• required_items (Sequence[str])

• severity (ValidationSeverity)

sloth.mmcif.rules.cross_ordering(item_a, item_b, op='<', severity=ValidationSeverity.WARNING)

Cross-checker: compare a value in cat_a against a value in cat_b.

Return type:

Callable[[Category, Category], None]

Parameters:

• item_a (str)

• item_b (str)

• op (str)

• severity (ValidationSeverity)