Extensions Guide

HCDF has a built-in extension mechanism that allows vendor-specific or domain-specific data to live alongside the core schema without modifying it. Extensions use reverse-DNS domain identifiers and explicit versioning to prevent conflicts and allow evolution.

How Extensions Work

An <extension> element can appear as a child of any <comp>. It carries a domain attribute (reverse-DNS identifier) and a version attribute. Inside, any well-formed XML is accepted. The HCDF schema declares xs:any processContents="lax" for the extension body, so the core validator will not reject unknown elements.

<extension domain="org.example.my-domain" version="1.0">
  <!-- Any well-formed XML here -->
  <custom-element attribute="value">
    <nested>data</nested>
  </custom-element>
</extension>

How to Write an Extension

1. Choose a domain: Use reverse-DNS notation. If your organization is example.org, your domain is org.example.feature-name. CogniPilot extensions use org.cognipilot.*.
2. Version it: Start at 1.0. Increment the minor version for backward-compatible additions, the major version for breaking changes.
3. Document it: Write a guide page (like the IMU Stability example) explaining what data your extension carries, why it is an extension rather than core, and how agents should use it.
4. Optionally provide an XSD: You can write an XSD for your extension's inner elements. Validators can then check extension content with processContents="strict" if the extension schema is available.
5. Register it: Submit a pull request to the HCDF repository adding your extension to the registry (see below).

Registered Extensions

Example: ROS 2 Topic Mapping

The org.ros2 extension maps each sensor and motor to a ROS 2 topic name, message type, and QoS profile. This allows a ROS 2 launch system to auto-configure publishers and subscribers from the HCDF file without manual topic remapping.

<extension domain="org.ros2" version="1.0">
  <topic-map>
    <topic sensor="imu0" name="/imu/data"
           type="sensor_msgs/msg/Imu" qos="sensor_data"/>
    <topic sensor="mag0" name="/mag/data"
           type="sensor_msgs/msg/MagneticField" qos="sensor_data"/>
    <topic sensor="baro0" name="/baro/data"
           type="sensor_msgs/msg/FluidPressure" qos="sensor_data"/>
    <topic sensor="gnss0" name="/gnss/fix"
           type="sensor_msgs/msg/NavSatFix" qos="sensor_data"/>
    <topic sensor="optical_flow0" name="/optical_flow"
           type="synapse_msgs/msg/OpticalFlow" qos="sensor_data"/>
    <topic sensor="camera0" name="/camera/image_raw"
           type="sensor_msgs/msg/Image" qos="sensor_data"/>
    <topic motor="prop_fl" name="/esc/fl/command"
           type="actuator_msgs/msg/MotorCommand" qos="reliable"/>
  </topic-map>
</extension>

Example: Gazebo Simulation

The org.gazebosim extension carries physics engine settings and plugin configurations. This data is used when generating an SDF world from the HCDF file, or when a Gazebo bridge reads the HCDF directly.

<extension domain="org.gazebosim" version="1.0">
  <physics>
    <engine>ode</engine>
    <max-step-size>0.001</max-step-size>
    <real-time-factor>1.0</real-time-factor>
  </physics>
  <plugin name="aerodynamics" filename="libAerodynamicsPlugin.so">
    <link>frame</link>
    <air-density>1.225</air-density>
    <forward-drag-coefficient>0.05</forward-drag-coefficient>
    <upward-drag-coefficient>0.1</upward-drag-coefficient>
  </plugin>
  <plugin name="motor_model" filename="libMotorModelPlugin.so">
    <motor>prop_fl</motor>
    <turning-direction>ccw</turning-direction>
    <time-constant-up>0.0125</time-constant-up>
    <time-constant-down>0.025</time-constant-down>
    <rotor-drag-coefficient>0.00025</rotor-drag-coefficient>
    <rolling-moment-coefficient>1e-6</rolling-moment-coefficient>
  </plugin>
</extension>

How to Register a New Extension

1. Fork the HCDF repository.
2. Add your extension documentation to docs/extensions/ (a markdown file following the IMU Stability pattern).
3. Optionally add an XSD to schema/extensions/.
4. Add an entry to the extension registry in docs/extensions/registry.md with your domain, version, description, and maintainer contact.
5. Submit a pull request. The HCDF maintainers will review for naming conflicts and documentation completeness.