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 by convention and may declare a version to prevent conflicts and allow evolution.

How Extensions Work

An <extension> element can appear at document level, at component level, or on a joint. It carries a required domain attribute (a reverse-DNS identifier by convention) and an optional version attribute. Inside, it accepts arbitrary well-formed child elements. 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">
  <!-- Arbitrary well-formed child elements can appear 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 consumers should use it.
4. Optionally provide an XSD: You can write an XSD for your extension's inner elements. Extension-aware tooling can validate that content in a separate pass. The core HCDF extension container remains lax and does not switch itself to strict processing.
5. List it: Submit a pull request to add your extension to the curated documentation listing described below.

Documented 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. ROS-aware tooling can consume these declarations when configuring publishers and subscribers or checking topic mappings.

<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">
  <gazebo-sim>
  <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>
  </gazebo-sim>
</extension>

How to Add an Extension to the Listing

1. Fork the HCDF repository.
2. Add a project-facing guide under website/extensions/, following the IMU Stability page pattern.
3. Optionally add an XSD named hcdf-ext-<name>.xsd under extensions/.
4. Add the extension to the curated list in website/extensions/index.html. For an XSD-backed extension, also add its generated reference page under website/spec/extensions/ and its regeneration command to the Pages workflow.
5. Submit a pull request. The HCDF maintainers will review for naming conflicts and documentation completeness.