Validation Checks

The validation system is built from modular, single-responsibility checks. Each check targets one specific aspect of the robot model and can be run independently or composed into a full validation pipeline.

Abstract Base

class linkforge.core.validation.ValidationCheck

Bases: ABC

Abstract base class for a single, focused validation rule.

All concrete checks must implement run(). Checks are stateless by design — all output is written into the provided ValidationResult.

abstractmethod run(robot, result)

Apply this check, writing errors and warnings into result.

Parameters:

• robot (Robot) – The robot model to validate.

• result (ValidationResult) – The shared result object to append errors/warnings to.

Return type:

None

Built-in Checks

class linkforge.core.validation.HasLinksCheck

Bases: ValidationCheck

Check that the robot has at least one link.

run(robot, result)

Check that robot has at least one link.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.DuplicateNameCheck

Bases: ValidationCheck

Check for duplicate link and joint names.

run(robot, result)

Check for duplicate link and joint names.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.JointReferenceCheck

Bases: ValidationCheck

Check that all joints reference existing links.

run(robot, result)

Check that all joints reference valid links.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.TreeStructureCheck

Bases: ValidationCheck

Check kinematic tree integrity: cycles, root link, and connectivity.

run(robot, result)

Check kinematic tree structure.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.MassPropertiesCheck

Bases: ValidationCheck

Check for mass and inertia issues (warnings).

run(robot, result)

Check for mass property health.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.GeometryCheck

Bases: ValidationCheck

Check for missing visual and collision geometry (warnings).

run(robot, result)

Check for geometry warnings.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.Ros2ControlCheck

Bases: ValidationCheck

Check that ros2_control joints reference existing robot joints.

run(robot, result)

Check ros2_control joint existence.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

class linkforge.core.validation.MimicChainCheck

Bases: ValidationCheck

Check for invalid or circular mimic joint configurations.

run(robot, result)

Check for invalid mimic joint configurations.

Parameters:

• robot (Robot)

• result (ValidationResult)

Return type:

None

---

Usage Examples

Run the full validator

The standard workflow — runs all registered checks in order:

from linkforge.core.validation import RobotValidator

validator = RobotValidator()
result = validator.validate(robot)

if not result.is_valid:
    for error in result.errors:
        print(f"[ERROR] {error.title}: {error.message}")

Run a single check in isolation

Useful for targeted testing or when building a custom validation pipeline:

from linkforge.core.validation import TreeStructureCheck, ValidationResult

result = ValidationResult()
TreeStructureCheck().run(robot, result)

if result.errors:
    print("Tree structure is invalid:")
    for err in result.errors:
        print(f"  - {err.message}")
else:
    print("Tree structure is valid.")

Build a custom validation pipeline

Pick and compose only the checks you need:

from linkforge.core.validation import (
    HasLinksCheck,
    DuplicateNameCheck,
    MassPropertiesCheck,
    ValidationResult,
)

checks = [HasLinksCheck(), DuplicateNameCheck(), MassPropertiesCheck()]
result = ValidationResult()

for check in checks:
    check.run(robot, result)

print(f"Errors: {len(result.errors)}, Warnings: {len(result.warnings)}")

Tip

All checks are stateless. The same check instance can be run against multiple robots in sequence without any side effects.