The robotheca.yaml guide

robotheca.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.

robotheca.yaml version 1.0. Last updated: 8 November 2026. The full text of the standard: the robotheca.yaml specification.

Make my robotheca.yaml

Paste your repository: Robotheca reads it as its import does and proposes your file, ready to check and copy. What your files do not say is left for you to fill in.

What it is and where it goes

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

Its first name was robot.yaml. A file with that name is still read, the same way, and always will be. When a repository has both, Robotheca reads robotheca.yaml. Another tool, Robocorp, also uses the name robot.yaml for software robots: such a file does not describe a robot, and Robotheca leaves it out.

It is a YAML file of at most 64 KB. Your files stay in the repository: robotheca.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. The current version is 1.0. Files written for 0.1 stay valid, forever; the fields marked “New in 1.0” need format_version: "1.0".

You don't need a robotheca.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 robotheca.yaml to download and add to your repository.

Required fields

Every robotheca.yaml has these 8 fields.

format_versionText: "1.0" or "0.1"

The version of the format. Write it in quotes: without them, YAML reads a number, and the file is refused. Use "1.0" for a new file. A file that says "0.1" stays valid, but the fields marked “New in 1.0” are allowed only in a file that says "1.0".

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”. A project at its end of life shows “End of life”: it can still be built from its files, but nobody updates it.

Values: idea (designed, not built), in_progress (being built), built (it works), tested (tested on real hardware, with tested.date) or end_of_life (you stopped the project; new in 1.0)

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, then amount_max and note

The price of the parts to build the whole robot once: the parts it needs, with the cheapest option where there is a choice; without tools, optional parts or shipping. 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. For a range, amount is the low end and amount_max the high end, at least amount. note says what the figure covers, at most 200 characters, for example “without the camera”. amount_max and note: New in 1.0.

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. Robotheca recognises these words: 3D printer, Soldering iron, Multimeter, Oscilloscope, CNC machine, Laser cutter and Microcontroller programmer. Any other word is allowed.

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.mujocoPath

The robot's main MuJoCo file, an .xml file (MJCF), for example mjcf/scene.xml. Robotheca then uses your choice instead of guessing it from the file names. New in 1.0.

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, url and license

AI models made for the robot, for example on Hugging Face. Each has a name and a url; both are needed. license is the licence of the model's weights, an SPDX expression, when it differs from the code's. license: New in 1.0.

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. code is code kept in another repository, such as firmware; dataset is recorded data, such as demonstrations. code and dataset: New in 1.0.

Values: bom, docs, video, forum, cad, shop, code (1.0) or dataset (1.0)

closed_partsList of name, note and kind

What 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. kind is part (the default) or software, for closed software such as a driver published as a program only. kind: New in 1.0.

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 1.0 and is valid. Copy it, then keep only what applies to your robot.

robotheca.yaml

# An example only: Example Hexapod H6 is a fictional robot.
# Its repository and its links do not exist.
format_version: "1.0"
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
  amount_max: 380
  currency: EUR
  note: The higher figure is with metal-gear servos.
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/
  mujoco: simulation/mjcf/scene.xml
  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
    license: Apache-2.0
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 }
  - { type: code, url: https://example.org/hexapod-h6/firmware, label: Servo board firmware }
  - { type: dataset, url: https://example.org/hexapod-h6/walking-data, label: Recorded walks }
closed_parts:
  - name: Servo driver board
    note: Bought ready-made; its design is not published.
  - name: Servo board configuration tool
    note: Published as a program only, without its source.
    kind: software

How the importer uses it

With a robotheca.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 robotheca.yaml at the root. It reads every file as data, and never runs anything from the repository.

A valid robotheca.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 robotheca.yaml gives other licenses than those files, the suggestion cannot be sent: only you can publish it.
A robotheca.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 robotheca.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 robotheca.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:

robotheca.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 robotheca.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 robotheca.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

Check your file on Robotheca: paste it or choose it on your computer, and each problem is shown in plain words, with its line. It is checked in your browser: nothing is sent or kept.

To check it on every change, add a GitHub Action to your repository. robotheca/validate-robot-yaml (opens in a new tab) is a GitHub Action that checks robotheca.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/robotheca-yaml.yml

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

For a file still named robot.yaml, leave out the two lines with: and path:. 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 robotheca.yaml files.