The robot.yaml guide

robot.yaml is a small file at the root of a robot's repository. It describes the robot in a standard way, so that any website or tool, starting with Robotheca, can understand it: what it is, what it costs, how hard it is, under which licenses, and where its files are.

robot.yaml version 0.1. Last updated: 4 November 2026.

What it is and where it goes

Put it at the root of the repository, named robot.yaml in lower case. Robotheca does not look for it in a folder, or under another name such as robot.yml.

It is a YAML file of at most 64 KB. Your files stay in the repository: robot.yaml only says where they are, by their paths.

category and difficulty take fixed English values, so that tools can filter and compare robots. Only the fields on this page are allowed: an unknown field, or a typo such as summery, makes the file invalid.

The format is versioned: format_version is required, and new fields come in later versions without breaking files written for 0.1.

You don't need a robot.yaml to import a robot: without one, Robotheca reads the files and the README (section F). And you don't have to write it by hand: once you have published your own robot, the import's last step offers its robot.yaml to download and add to your repository.

Required fields

Every robot.yaml has these 8 fields.

format_versionText: "0.1"

The version of the format. Write it in quotes: without them, YAML reads the number 0.1, and the file is refused.

nameText, at most 80 characters

The robot's name, as people should see it. The address of its page on Robotheca is made from it: Example Hexapod H6 becomes /robots/example-hexapod-h6.

summaryText, at most 200 characters

One or two sentences: what the robot is and what it does.

categoryOne value

The kind of robot. Robotheca shows it as the robot's type, with the label in brackets when it differs from the value. hexapod is for robots with six legs.

Values: arm (Robot arm), rover (Wheeled), humanoid, quadruped, hexapod, drone, self_driving_scale (Self-driving 1:10), home or other

difficultyOne value

How hard the robot is to build, shown as its level.

Values: beginner, intermediate or advanced

license.hardwareSPDX license expression

The license of the hardware designs: the CAD files, the parts to print, the boards. For example CERN-OHL-S-2.0 or CC-BY-NC-SA-4.0.

license.softwareSPDX license expression

The license of the code. For example Apache-2.0, or MIT OR Apache-2.0.

source.repositoryWeb address

The repository's home page, starting with https:// or http://.

Licenses

Licenses are SPDX identifiers or expressions, such as MIT, CERN-OHL-S-2.0, MIT OR Apache-2.0 or GPL-2.0-only WITH Classpath-exception-2.0: see the SPDX license list (opens in a new tab). Hardware and software are separate because they are usually under different licenses. A non-commercial license (CC-BY-NC…) means that kits and parts cannot be sold.

When you import your own robot, the robot card checks that each license is a valid SPDX expression.

Optional fields

Fill in what applies to your robot. Paths and web addresses follow the rules of section D.

statusOne value

Where the project stands. An idea or a project in progress is never labelled “Ready to build”.

Values: idea (designed, not built), in_progress (being built), built (it works) or tested (tested on real hardware, with tested.date)

license.documentationSPDX license expression

The license of the guide, its text and pictures, for example CC-BY-SA-4.0. It decides whether others may reuse or adapt the guide, translations included. Without it, the hardware and software licenses apply to the guide.

source.refText

The tag or commit this description refers to, for example v1.2.0.

estimated_costamount and currency

The total cost of the parts as you state it, shipping excluded. amount is a number, 0 or more; currency is a three-letter ISO 4217 code in capitals, such as EUR, USD or CNY. Both are needed. The cost is kept in its own currency, as you wrote it.

build_time_hoursNumber, 0 or more

Hands-on time to build the robot, in hours.

print_time_hoursNumber, 0 or more

3D printer time, in hours.

toolsList of text

The tools needed to build it, for example 3D printer or soldering iron.

files.urdfPath

The robot description (a .urdf file). Robotheca builds the 3D view from it and its STL meshes.

files.parts_3dPath

The folder of parts to print (STL, 3MF or OBJ), for example stl/. Without a URDF, its STL files make the 3D view.

files.cadPath

The CAD source files: STEP, Fusion 360, SolidWorks, FreeCAD… With neither a URDF nor STL parts to show, Robotheca can turn its STEP files into the 3D view.

files.electronicsPath

The circuit files: KiCad, .brd or Gerber files.

files.bomPath

The parts list: a CSV, TSV or Markdown table, one line per part with its name, quantity and price. Robotheca reads it into the robot page's parts list.

files.docsPath

The documentation folder.

files.simulationPath

Simulation files, for MuJoCo, Gazebo, Webots or Isaac.

files.imagesList of paths

Pictures of the robot. The first is its photo: a JPEG, PNG, WebP or GIF file (never SVG), at most 5 MB, or 25 MB for an animated GIF.

software.frameworkText

The software framework the robot runs on, for example lerobot or ros2.

software.ros_versionText

The ROS version, when the robot uses ROS.

ai_modelsList of name and url

AI models made for the robot, for example on Hugging Face. Each has a name and a url; both are needed.

specsFree keys: text, number or true/false

Specifications, one key: value per line, with the unit in the key: height_cm, weight_kg, reach_mm, dof, power…

build_stepsList of steps

The build steps, in order. Each has a title (needed), and may have hours and where its instructions are: doc, a file in the repository (docs/assembly.md), or url, a web page such as a docs site or a video. Not both.

part_linksFree keys: a whole number, 1 or more

Links a link or mesh of the 3D model, by its name, to a line of the parts list. The first line of the parts list is 1.

testedon_hardware and date

on_hardware: true or false. date: the day of the test, written YYYY-MM-DD.

maintainersList of name and github

The people who look after the project: a name (needed) and their GitHub user name.

external_linksList of type, url and label

Resources kept outside the repository, for example a parts spreadsheet or a build video. type (one of the values below) and url are needed; label is optional, at most 80 characters.

Values: bom, docs, video, forum, cad or shop

closed_partsList of name and note

Parts the robot needs whose design is not open, for example a control board that is only sold. Both are needed: name at most 120 characters, note at most 200.

Paths and limits

Web addresses

source.repository, ai_models[].url, external_links[].url and build_steps[].url are full web addresses that start with http:// or https://. Other kinds (javascript:, data:, file:…) are refused.

File paths

files.*, files.images[] and build_steps[].doc are paths from the repository's root, with / between folders, that stay inside the repository: no / or ~ at the start, no .. folder, no backslash, no scheme or drive (https:, C:), no control characters. End a folder's path with /, as in stl/. A path points to a file in the repository, never to a copy kept elsewhere.

Free keys

The keys of specs and part_links can be any text except __proto__.

Reading the file

A schema cannot describe the file itself, so Robotheca also applies these limits:

UTF-8 text, at most 64 KB.
One YAML 1.2 document, whose top level is a mapping.
No key twice, at any level.
Only plain YAML values: text, numbers, true or false, null, lists and mappings. No tags such as !!binary or !!python/…, and merge keys (<<) are not applied.
At most 32 levels of nested lists and mappings.
Aliases (*name) are allowed; Robotheca expands at most 50.

A full example

An example only: Example Hexapod H6 is a fictional robot, and its repository and links do not exist. The file uses every field of version 0.1 and is valid. Copy it, then keep only what applies to your robot.

robot.yaml

# An example only: Example Hexapod H6 is a fictional robot.
# Its repository and its links do not exist.
format_version: "0.1"
name: Example Hexapod H6
summary: A six-legged walking robot with 18 servos, printed in PLA and run by a Raspberry Pi, that walks and turns on flat ground.
category: hexapod
difficulty: intermediate
status: tested
license:
  hardware: CERN-OHL-S-2.0
  software: Apache-2.0
  documentation: CC-BY-SA-4.0
source:
  repository: https://github.com/example/hexapod-h6
  ref: v1.2.0
estimated_cost:
  amount: 320
  currency: EUR
build_time_hours: 12
print_time_hours: 40
tools: ["3D printer", "soldering iron", "hex keys"]
files:
  urdf: hexapod_h6_description/urdf/hexapod_h6.urdf
  parts_3d: stl/
  cad: hexapod_h6_description/cad/
  electronics: electronics/
  bom: bom.csv
  docs: docs/
  simulation: simulation/
  images: ["docs/img/hexapod-h6.jpg"]
software:
  framework: ros2
  ros_version: jazzy
ai_models:
  - name: Hexapod H6 walking policy
    url: https://huggingface.co/example/hexapod-h6-walk
specs:
  legs: 6
  dof: 18
  weight_kg: 1.6
  battery: 2S LiPo
build_steps:
  - { title: Print the parts, hours: 40, doc: docs/01-print.md }
  - { title: Assemble the legs, hours: 5, doc: docs/02-legs.md }
  - { title: Wire the servo board, hours: 3, doc: docs/03-wiring.md }
  - { title: Install the software, hours: 1, doc: docs/04-software.md }
  - { title: Calibrate the legs, hours: 1, url: https://example.org/hexapod-h6/calibrate }
part_links:
  coxa_link: 1
  femur_link: 2
  tibia_link: 3
tested:
  on_hardware: true
  date: "2026-09-15"
maintainers:
  - { name: Example Maker, github: example }
external_links:
  - { type: video, url: https://example.org/hexapod-h6/build-video, label: Build video }
  - { type: forum, url: https://example.org/hexapod-h6/forum, label: Questions and answers }
closed_parts:
  - name: Servo driver board
    note: Bought ready-made; its design is not published.

How the importer uses it

With a robot.yaml

When you import a public GitHub repository, Robotheca reads it at its latest commit (or at the branch of a /tree/… link) and looks for robot.yaml at the root. It reads every file as data, and never runs anything from the repository.

A valid robot.yaml fills in the robot card as you wrote it, with no automatic fill-in.
Its files.bom is the first parts list Robotheca tries.
The robot is pinned to the commit Robotheca read, and its source is the repository you imported: source.ref is not used for that.
When someone else suggests your robot, its licenses come only from the repository's license files. If robot.yaml gives other licenses than those files, the suggestion cannot be sent: only you can publish it.
A robot.yaml that is not valid is shown under “Files we found” with its first problems, and the card is filled in as if there were none.

What Robotheca finds by itself

With or without robot.yaml, Robotheca looks through the whole repository, by the names of files and folders:

Robot description: every .urdf file, in any folder, read with its meshes; the most complete first. A mesh written as package://my_robot_description/meshes/base.stl is found by its path after the package name, so the package folder can have any name. The 3D view needs STL meshes: other mesh files count as missing. .xacro files are found but never expanded (xacro can run code): add the generated .urdf to the repository.
Parts to print: STL, 3MF and OBJ files, in the folder that holds most of them. The URDF's meshes are not counted, nor files in simulation or robot description folders (sim, simulation, mujoco, mjcf, gazebo, isaac…, maniskill, and every folder whose name ends in description, such as my_robot_description).
CAD files: STEP, IGES, Fusion 360, SolidWorks, FreeCAD and OpenSCAD files, in any folder.
Electronics: KiCad, .brd and Gerber files, in any folder.
Parts list: files named like bom.csv, parts_list.md or bill_of_materials.tsv, then a README in a parts, hardware or design folder, then the main README; the first with a parts table is used.
Documentation: a docs, doc or documentation folder at the root.
Photo: the repository's pictures, those the README shows first; pictures whose names say they are not a photo (a logo, a diagram, a schematic…) are left out.
Licenses: read from the license files (LICENSE, COPYING, files such as HARDWARE-LICENSE.txt, or a LICENSES/ folder), never from GitHub's license label.

Without robot.yaml, the rest of the card (name, summary, type, level…) is filled in from the README when automatic fill-in is available, and every field filled in that way is marked “Please check”.

Files in folders with other names

Your files can be in any folder, for example a ROS package called my_robot_description. To say exactly which file or folder you mean, name it in files:

robot.yaml (part of it)

files:
  urdf: my_robot_description/urdf/my_robot.urdf
  cad: my_robot_description/cad/

On the robot card you check before publishing, the URDF, the folder of parts to print, the parts list and the photo are chosen from what Robotheca found; your robot.yaml's choice is selected when it is one of them. A URDF is offered when Robotheca can read it and at least one of its meshes is an STL file in the repository. The other paths (cad, electronics, docs, simulation) are kept as you wrote them.

When you publish

The card becomes the robot.yaml that will be published, shown at the review step. It goes through the same checks as every robot on Robotheca: each path must be in the repository at the pinned commit, the parts list is read, the 3D view is prepared, and each part_links entry must point to a line of the parts list and to a link or mesh of the 3D model. If a check fails, its problems are listed and nothing is published.

Some fields count in the buildability score: build_steps (from 3 steps), software.framework, a folder named in files.parts_3d, files.cad or files.simulation, external_links of type bom or cad, and closed_parts, which take points off. See how we score.

Import a robot from GitHub

Check your file

robotheca/validate-robot-yaml (opens in a new tab) is a GitHub Action that checks robot.yaml against the same schema robotheca.org uses. Each problem appears as an annotation on its line, and it runs free in public repositories. Add this file to your robot's repository:

.github/workflows/robot-yaml.yml

name: robot.yaml
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: robotheca/validate-robot-yaml@v1

It checks the required fields, their types and allowed values, and that there are no unknown fields. It does not check that your paths exist, nor the limits of section D: Robotheca checks those when you import and publish.

The schema itself, robot.schema.json (JSON Schema 2020-12), is published in the same repository under the Apache-2.0 license, for tools that read robot.yaml files.

AWhat it is and where it goes

BRequired fields