The robotheca.yaml specification

Version 1.0. The full text of the standard, for anyone who writes a robotheca.yaml file or a tool that reads one.

Writing your first file? The robotheca.yaml guide explains each field with an example.
Check your file in your browser.
The schemas (JSON Schema 2020-12, Apache-2.0): version 1.0 and version 0.1.

robotheca.yaml is a small file placed 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.

Machine-readable schema: robotheca.schema.json (JSON Schema 2020-12). Example: examples/desk-arm-01.robotheca.yaml. Version 0.1: robot-yaml-v0.1.md and robot.schema.json, unchanged.

The file's name

Name it robotheca.yaml, in lower case, at the root of the repository.
Its first name was robot.yaml. Tools should read a file with that name the same way, forever. When a repository has both, robotheca.yaml is read.
Another tool (Robocorp) also uses the name robot.yaml, for software robots. Such a file does not follow this format, fails the schema and should be left out.

Principles

Small first. A field nobody fills in is worse than no field.
Paths, not copies. Files stay in the repository; robotheca.yaml points to them.
Stable vocabulary. Enums (category, difficulty, status) use fixed English values so tools can filter and compare. Interfaces translate them.
Facts, not labels. The file states what the creator knows. Labels a website derives from it (such as "Ready to build", or whether commercial use is allowed) are that website's decisions.
Versioned. format_version is required.

Versions

A file says its version: format_version: "0.1" or format_version: "1.0", in quotes.
A file that says "0.1" is checked against robot.schema.json, exactly as before. Every 0.1 file stays valid, forever.
A file that says "1.0" is checked against robotheca.schema.json. The fields new in 1.0 (marked 1.0 below) are allowed only there, so tools written for 0.1 never meet a field they do not know in a "0.1" file.
Versions 1.x only add optional fields. Within 1.x a field is never removed and its meaning never changes.

Fields

Field	Required	Type	Notes
format_version	yes	"0.1" or "1.0"
name	yes	string ≤ 80 chars	Display name
summary	yes	string ≤ 200 chars	One or two sentences
category	yes	enum	arm, rover, humanoid, quadruped, hexapod, drone, self_driving_scale, home, other
difficulty	yes	enum	beginner, intermediate, advanced
status	no	enum	idea, in_progress, built, tested, 1.0: end_of_life. See "Status" below
license.hardware	yes	SPDX expression	e.g. CERN-OHL-S-2.0, CC-BY-NC-SA-4.0
license.software	yes	SPDX expression	e.g. Apache-2.0, MIT OR Apache-2.0
license.documentation	no	SPDX expression	The guide's text and pictures, e.g. CC-BY-SA-4.0. When absent, the hardware and software licenses apply to it
source.repository	yes	web address	The project's home, http(s) only. It can be outside GitHub
source.ref	no	string	Tag or commit the description refers to
estimated_cost.amount	no*	number ≥ 0	See "Cost" below. *Required when `estimated_cost` is given
estimated_cost.currency	no*	ISO 4217 code	e.g. EUR, USD, CNY. Never converted. *Required with `amount`
estimated_cost.amount_max	no	number ≥ amount	1.0. The high end when the creator gives a range
estimated_cost.note	no	string ≤ 200 chars	1.0. What the figure covers, in the creator's words
build_time_hours	no	number	Hands-on time
print_time_hours	no	number	3D printer time
tools	no	string[]	Suggested words: "3D printer", "Soldering iron", "Multimeter", "Oscilloscope", "CNC machine", "Laser cutter", "Microcontroller programmer". Any other word is allowed
files	no	object	urdf, parts_3d, cad, electronics, bom, docs, simulation, images[], 1.0: mujoco. Repository paths
files.mujoco	no	repository path	1.0. The robot's main MuJoCo file (MJCF, an `.xml`). `files.simulation` stays, for a whole folder
software	no	object	framework (e.g. lerobot, ros2), ros_version
ai_models	no	object[]	name + url (http(s), e.g. Hugging Face), 1.0: license, the weights' licence as an SPDX expression
specs	no	object	Free key/values. Suggested keys: height_cm, weight_kg, dof, payload_kg, reach_mm, battery_wh
build_steps	no	object[]	title, hours, and where the step's instructions are: doc (repository path) or url (http(s)), not both
part_links	no	object	3D link or mesh name → BOM line number (1-based)
tested	no	object	on_hardware (bool), date (YYYY-MM-DD)
maintainers	no	object[]	name, github
external_links	no	object[]	type + url (http(s)) + optional label (≤ 80 chars). Types: bom, docs, video, forum, cad, shop, 1.0: code (code kept in another repository, such as firmware), dataset (recorded data, such as demonstrations)
closed_parts	no	object[]	name + note (≤ 200 chars): what the robot needs whose design is not open. 1.0: kind, `part` (the default: a physical part, such as a board that is only sold) or `software` (closed software, such as a binary-only SDK)

Status

idea: designed, not built.
in_progress: being built.
built: it works.
tested: tested on real hardware, with tested.date.
1.0: end_of_life: the creator stopped the project. It can still be built from its files, but nobody updates it.

Cost

estimated_cost is 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. It is the creator's figure, in the creator's currency, and tools never convert it in the file.

A creator who gives a range writes the low end in amount and the high end in amount_max (1.0). note (1.0) says what the figure covers when it is not obvious: "without the Jetson", "for the 6-servo version".

Web addresses and file paths

robotheca.yaml files come from repositories that tools do not control, so every tool must be able to show their links and paths safely.

Web addresses (source.repository, ai_models[].url, external_links[].url, build_steps[].url) are absolute URLs that start with http:// or https://. Other schemes (javascript:, data:, file:…) are invalid.
File paths (files.*, files.images[], build_steps[].doc) are relative to the repository root, use / as separator and stay inside the repository: no leading / or ~, no .. segment, no backslash, no scheme or drive prefix (https:, C:), no control characters. A trailing / marks a folder (stl/). Paths point to files in the repository, never to copies hosted elsewhere.
Free-form keys (specs, part_links) can be any text except __proto__.

These rules are part of the schema ($defs: webUrl, repoPath, freeKey). Currency codes are three capital letters from ISO 4217 ($defs.currencyCode). One rule is not in the schema, because a schema cannot compare two fields: estimated_cost.amount_max is at least estimated_cost.amount.

Reading a robotheca.yaml file

A JSON schema cannot describe the file itself, so tools should also apply these limits before validating. Robotheca applies all of them.

UTF-8 text, at most 64 KB.
One YAML 1.2 document whose top level is a mapping.
No duplicate keys at any level.
Only the plain YAML types: text, numbers, booleans, null, lists and mappings. No custom tags (!!binary, !!python/…, !thing). Merge keys (<<) are not applied.
At most 32 levels of nested lists and mappings.
Aliases (*name) are allowed, but tools may limit how far they expand; Robotheca allows 50 expansions.

Licenses

Use SPDX identifiers or SPDX expressions (MIT OR Apache-2.0, GPL-2.0-only WITH Classpath-exception-2.0). Hardware and software are separate because they are usually under different licenses. Non-commercial licenses (CC-BY-NC*) mean kits and parts cannot be sold. A guide often has a license of its own (license.documentation); it decides whether others may reuse or adapt the guide, translations included. An AI model's weights can have a license of their own too (ai_models[].license, 1.0).

How the format changes

Robotheca decides each version. Anyone can propose a change.

Changelog

1.0 (published: the date it goes live on robotheca.org)

The file's name is robotheca.yaml; robot.yaml is still read.
format_version can be "1.0". Files that say "0.1" stay valid and are read as before.
New, all optional: status: end_of_life; estimated_cost.amount_max and estimated_cost.note; files.mujoco; ai_models[].license; closed_parts[].kind; the code and dataset link types.
estimated_cost now says exactly what it covers.
Suggested words for tools and suggested keys for specs.

0.1 (October 2026): the first version. license.documentation and status added on 2026-10-10, hexapod on 2026-11-04.

License of this specification

The robotheca.yaml specification is published by Robotheca under the Creative Commons Attribution 4.0 International licence (CC BY 4.0): https://creativecommons.org/licenses/by/4.0/ (opens in a new tab). You may copy, share and adapt it, also commercially, if you credit Robotheca and link to the licence. The JSON schema and the checker are under the Apache License 2.0. Using the format in your own files needs no permission and no credit.