defined-rdf API Reference

Robot Description Framework — Pydantic models, YAML parser, and capability registry.

Models

models

Pydantic models for the Robot Description Framework.

Inertia

Bases: BaseModel

3x3 inertia tensor (symmetric) in kg·m².

Origin

Bases: BaseModel

Rigid-body pose expressed as translation and Euler angles (RPY).

MeshGeometry

Bases: BaseModel

Reference to an external mesh file.

BoxGeometry

Bases: BaseModel

Axis-aligned box geometry with dimensions [x, y, z] in metres.

CylinderGeometry

Bases: BaseModel

Cylinder geometry defined by radius and length in metres.

SphereGeometry

Bases: BaseModel

Sphere geometry defined by radius in metres.

LinkGeometry

Bases: BaseModel

Geometry for a link's visual or collision shape.

Exactly one of the geometry variants should be set.

Link

Bases: BaseModel

A rigid body in the robot's kinematic chain.

Joint

Bases: BaseModel

A kinematic joint connecting a parent link to a child link.

PhysicalDescription

Bases: BaseModel

Optional kinematic and geometric description of the robot body.

CapabilityType

Bases: str, Enum

Known capability types.

Capability

Bases: BaseModel

A single capability that a robot module provides.

Module

Bases: BaseModel

A hardware module that provides capabilities.

Robot

Bases: BaseModel

Top-level robot description.

capabilities property

Return a flat list of all capabilities across all modules.

has_capability(capability_type)

Return True if any module provides the given capability type.

Parameters:

Name	Type	Description	Default
capability_type	str	The capability type string to look for (e.g. "differential_drive").	required

Returns:

Type	Description
bool	True if the capability is present, False otherwise.

Robot Configuration

robot_config

Target-agnostic robot configuration extracted from RDF.

RobotConfig is the bridge between a parsed RDF Robot model and any target (sim or hardware). It extracts drive parameters and a dynamic sensor map so that consumers (CLI target layer, capability_reporter) don't need to understand the RDF module/capability nesting.

DriveConfig dataclass

Drive parameters -- always present (every robot moves).

RobotConfig dataclass

Target-agnostic robot configuration extracted from RDF.

Capabilities stored dynamically -- adding new types (IMU, GPS, depth_camera) doesn't change this structure.

has_sensor(sensor_type)

Return True if the robot has the given sensor type.

sensor_params(sensor_type)

Return parameters for the given sensor type.

Raises:

Type	Description
KeyError	If the sensor type is not present.

extract_robot_config(robot)

Extract a RobotConfig from a parsed Robot model.

Parameters:

Name	Type	Description	Default
robot	Robot	Parsed RDF Robot model.	required

Returns:

Type	Description
RobotConfig	A RobotConfig with drive parameters and dynamic sensor map.

Raises:

Type	Description
ValueError	If the robot has no differential_drive capability.

Parser

parser

Load and validate RDF YAML files.

load(path)

Load an RDF YAML file and return a validated Robot model.

If the file contains a physical_file field, the referenced YAML is loaded and merged into the physical field. The path is resolved relative to the directory containing the RDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the .rdf.yaml file.	required

Returns:

Type	Description
Robot	A validated Robot model.

Raises:

Type	Description
FileNotFoundError	If the file or referenced physical_file does not exist.
ValueError	If both physical and physical_file are specified.
ValidationError	If the data fails schema validation.

Capability Registry

registry

In-memory capability registry.

CapabilityRegistry

Registry of capabilities available on the current robot.

robot_name property

Return the robot's name.

__init__(robot)

Initialise the registry from a validated Robot model.

Parameters:

Name	Type	Description	Default
robot	Robot	A schema-valid Robot instance whose capabilities will be indexed by type for fast lookup.	required

has(capability_type)

Check if a capability type is registered.

get(capability_type)

Get a capability by type, or None if not registered.

list_types()

List all registered capability types.

check_requirements(required)

Check if all required capabilities are available.

Returns (all_met, missing_list).

Validator

validator

Semantic validation for RDF robot descriptions.

Goes beyond schema validation (Pydantic) to check physical self-consistency: capability parameters vs. physical description geometry and joints.

Severity

Bases: str, Enum

Severity level for validation results.

ValidationResult dataclass

A single validation finding.

Attributes:

Name	Type	Description
severity	Severity	Whether this is an error or warning.
capability	str	The capability type that triggered this result.
message	str	Human-readable description of the issue.

__str__()

Return formatted string representation.

validate(robot)

Validate physical self-consistency of a Robot model.

Runs all registered capability validators against the robot and collects errors and warnings.

Parameters:

Name	Type	Description	Default
robot	Robot	A schema-valid Robot model to check.	required

Returns:

Type	Description
list[ValidationResult]	A list of ValidationResult objects. Empty means all checks passed.

validate_or_raise(robot)

Validate and raise if any errors are found.

Warnings are collected but do not cause a raise.

Parameters:

Name	Type	Description	Default
robot	Robot	A schema-valid Robot model to check.	required

Returns:

Type	Description
Robot	The same Robot instance, unchanged.

Raises:

Type	Description
ValueError	If one or more ERROR-level results are found.