{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "kk-policy-bundle/1", "title": "A robot application bundle: / and .app", "description": "Robot application formats: legacy policy bundles and self-contained native robot applications. Each version declares its actual supported runtimes.", "x-files": [ { "path": "^bundle\\.json$", "required": true, "format": "json", "is": "this schema's document: every file, its size and SHA-256, and which host takes what" }, { "path": "^README\\.md$", "required": true, "format": "markdown", "is": "the integration guide, from deploy/fsm/BUNDLE_README.md" }, { "path": "^controller\\.toml$", "required": true, "format": "toml", "is": "the FSM: modes, the rules that switch between them, the keys and buttons", "namedBy": "fsm" }, { "path": "^manual\\.en\\.json$", "required": true, "format": "json", "schema": "#/$defs/manual", "is": "every key and button the bundle reads and what it does, in English, generated at build time", "namedBy": "manuals.en" }, { "path": "^manual\\.[a-z]{2}(-[A-Za-z]+)?\\.json$", "required": false, "format": "json", "schema": "#/$defs/manual", "is": "a translation of manual.en.json, added with `deploy.py --translate`", "namedBy": "manuals." }, { "path": "^reference\\.json$", "required": false, "format": "json", "is": "kk-policy-reference/1: recorded frames every host replays to measure that it agrees; absent only where onnxruntime was not installed at build time", "namedBy": "reference" }, { "path": "^[^/]+\\.trajectory\\.json$", "required": false, "format": "json", "is": "a recording a reference-guided mode is driven by, beside the contracts", "namedBy": "modes..trajectory" }, { "path": "^[a-z][a-z0-9_]*\\.json$", "required": true, "format": "json", "is": "one mode's contract (the export's layout.json): observation layout, joint order, gains, controls", "namedBy": "modes..contract" }, { "path": "^models/[a-z][a-z0-9_]*\\.onnx$", "required": true, "format": "onnx", "is": "a policy, for the browser and play; one per export, shared by the modes on it", "namedBy": "modes..models.onnx" }, { "path": "^models/[a-z][a-z0-9_]*\\.rknn$", "required": false, "format": "rknn", "is": "the same policy converted for the RK3576 NPU; a mode without one runs on a stub on the board", "namedBy": "modes..models.rknn" }, { "path": "^runtime/web/controller\\.wasm$", "required": true, "format": "wasm", "is": "the controller for a browser; one build for every CPU", "namedBy": "runtimes.web.wasm" }, { "path": "^runtime/web/controller\\.js$", "required": true, "format": "javascript", "is": "its wasm-bindgen binding", "namedBy": "runtimes.web.glue" }, { "path": "^runtime/mjlab/macosx-[a-z0-9._-]+/controller\\.so$", "required": false, "format": "mach-o", "is": "the same for macOS: macosx-universal2 is cross-built with zig, arm64 and x86_64 in one file, and loaded on any Mac whatever version its Python's platform string carries; a Mac that built the bundle adds its own under its exact platform", "namedBy": "runtimes.mjlab.extensions..file" }, { "path": "^runtime/mjlab/[a-z0-9._-]+/controller\\.so$", "required": false, "format": "elf-shared-object", "is": "the controller as a Python extension (abi3) for play --app, one per platform it was built on", "namedBy": "runtimes.mjlab.extensions..file" }, { "path": "^runtime/mjlab/win-[a-z0-9_]+/controller\\.pyd$", "required": false, "format": "pe-dll", "is": "the same, for play --app on Windows: cross-built with MinGW, importing python3.dll and nothing outside Windows itself", "namedBy": "runtimes.mjlab.extensions..file" }, { "path": "^runtime/board/controller$", "required": false, "format": "elf-aarch64", "is": "the robot's whole program, cross-compiled; absent until deploy/fsm/docker-build.sh has run, which bundle.json's notes then say", "namedBy": "runtimes.board.file" } ], "$defs": { "mode": { "type": "object", "required": [ "models", "contract", "observation", "action" ], "additionalProperties": false, "properties": { "models": { "description": "The mode's policy in every format a host runs: `onnx` always, `rknn` once converted.", "type": "object", "required": [ "onnx" ], "additionalProperties": false, "properties": { "onnx": { "type": "string", "pattern": "^models/[a-z][a-z0-9_]*\\.onnx$" }, "rknn": { "type": "string", "pattern": "^models/[a-z][a-z0-9_]*\\.rknn$" } } }, "contract": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.json$" }, "observation": { "type": "integer" }, "action": { "type": "integer" }, "trajectory": { "type": "string", "pattern": "\\.trajectory\\.json$" } } }, "webRuntime": { "type": "object", "required": [ "model", "glue", "wasm", "commit", "unverifiedByTheConsumer" ], "properties": { "model": { "const": "onnx" }, "glue": { "const": "runtime/web/controller.js" }, "wasm": { "const": "runtime/web/controller.wasm" }, "commit": { "type": "string" }, "unverifiedByTheConsumer": { "type": "string" } } }, "mjlabRuntime": { "type": "object", "required": [ "model", "extensions", "commit" ], "properties": { "model": { "const": "onnx" }, "extensions": { "description": "By `sysconfig.get_platform()` of the machine it runs on: the build machine's, and `win-amd64` and `macosx-universal2`, cross-built. macOS is keyed without a version (`mjrl.app_play.extension_for`).", "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "required": [ "file", "abi" ], "properties": { "file": { "type": "string", "pattern": "^runtime/mjlab/[a-z0-9._-]+/controller\\.(so|pyd)$" }, "abi": { "type": "string" } } } }, "commit": { "type": "string" } } }, "boardRuntime": { "type": "object", "required": [ "model", "file", "platform", "commit" ], "properties": { "model": { "const": "rknn" }, "file": { "const": "runtime/board/controller" }, "platform": { "const": "aarch64-unknown-linux-gnu" }, "commit": { "type": "string" } } }, "manual": { "description": "manual..json. A translation keeps every field of manual.en.json and changes only the text ones: source, summary, enter, leave, keyboard, pad, does. The pad and the keyboard are listed apart, in each mode and among the switches (since 2026-09-29).", "type": "object", "required": [ "schema", "language", "bundle", "source", "modes", "switches" ], "additionalProperties": false, "properties": { "schema": { "const": "kk-bundle-manual/1" }, "language": { "type": "string", "pattern": "^[a-z]{2}(-[A-Za-z]+)?$" }, "bundle": { "type": "string" }, "source": { "type": "string" }, "modes": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "mode", "task", "default", "summary", "enter", "leave", "keyboard", "controls", "keys" ], "additionalProperties": false, "properties": { "mode": { "type": "string" }, "task": { "type": [ "string", "null" ] }, "default": { "type": "boolean" }, "summary": { "type": "string" }, "enter": { "type": "string" }, "leave": { "type": "string" }, "keyboard": { "type": "string" }, "controls": { "description": "The pad in this mode: each control and what it does.", "type": "array", "items": { "type": "object", "required": [ "control", "pad", "does" ], "additionalProperties": false, "properties": { "control": { "type": "string" }, "pad": { "type": "string" }, "does": { "type": "string" } } } }, "keys": { "description": "The keyboard in this mode: each keystroke, as printed on the keys, and what it does.", "type": "array", "items": { "type": "object", "required": [ "key", "does" ], "additionalProperties": false, "properties": { "key": { "type": "string" }, "does": { "type": "string" } } } } } } }, "switches": { "type": "array", "items": { "type": "object", "required": [ "device", "control", "with", "keys", "pad", "does", "from" ], "additionalProperties": false, "properties": { "device": { "enum": [ "pad", "keyboard" ] }, "control": { "type": "string" }, "with": { "type": [ "string", "null" ] }, "keys": { "type": "array", "items": { "type": "string" } }, "pad": { "type": [ "string", "null" ] }, "does": { "type": "string" }, "from": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } } }, "policyBundle": { "type": "object", "required": [ "schema", "runtimes", "fsm", "modes", "notes", "files", "manuals", "reference" ], "additionalProperties": false, "properties": { "schema": { "const": "kk-policy-bundle/1" }, "runtimes": { "description": "Each host's build of the controller, keyed by host. A host whose build this bundle does not carry has no entry, and `notes` says how to add it.", "type": "object", "required": [ "web" ], "additionalProperties": false, "properties": { "web": { "$ref": "#/$defs/webRuntime" }, "mjlab": { "$ref": "#/$defs/mjlabRuntime" }, "board": { "$ref": "#/$defs/boardRuntime" } } }, "fsm": { "const": "controller.toml" }, "modes": { "description": "Every state that runs a model, by the name controller.toml gives it.", "type": "object", "minProperties": 1, "patternProperties": { "^[a-z][a-z0-9_]*$": { "$ref": "#/$defs/mode" } }, "additionalProperties": false }, "notes": { "type": "array", "items": { "type": "string" } }, "reference": { "description": "The reference vectors' file, or null when none could be recorded.", "type": [ "string", "null" ] }, "manuals": { "description": "The manual per language. English is always there; a translation is added after the build.", "type": "object", "required": [ "en" ], "patternProperties": { "^[a-z]{2}(-[A-Za-z]+)?$": { "type": "string", "pattern": "^manual\\.[a-z]{2}(-[A-Za-z]+)?\\.json$" } }, "additionalProperties": false }, "built_from": { "description": "Where every mode came from, for a bundle built from deploy/manifests.json.", "type": "object", "additionalProperties": { "type": "object", "required": [ "task", "from", "export" ], "properties": { "task": { "type": "string" }, "from": { "type": "string" }, "export": { "type": "string" } } } }, "files": { "description": "Every file in the bundle but bundle.json itself, by its path inside it.", "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "required": [ "bytes", "sha256" ], "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } }, "robotApp": { "type": "object", "required": [ "schema", "robot_id", "model", "default_mode", "modes", "controller", "manuals", "reference", "verification", "runtimes", "capabilities", "source", "files" ], "additionalProperties": false, "properties": { "schema": { "const": "mjrl-robot-app/1" }, "robot_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "model": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$" }, "default_mode": { "type": "string" }, "modes": { "type": "object", "minProperties": 1, "patternProperties": { "^[a-z][a-z0-9_]*$": { "type": "object", "required": [ "control_mode", "contract" ], "additionalProperties": false, "properties": { "control_mode": { "enum": [ "rl_onnx", "ik_mocap", "wheeled_velocity", "cpg_keyframe", "model_viewer" ] }, "contract": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$" }, "controls": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$" }, "policy": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$" }, "layout": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$" }, "verification": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*[\\\\:]).+$" } }, "allOf": [ { "if": { "properties": { "control_mode": { "const": "rl_onnx" } } }, "then": { "required": [ "policy", "layout" ] } }, { "if": { "properties": { "control_mode": { "not": { "const": "model_viewer" } } } }, "then": { "required": [ "verification" ] } } ] } }, "additionalProperties": false }, "controller": { "const": "controller.toml" }, "manuals": { "description": "The manual per language. English is always there; a translation is added after the build.", "type": "object", "required": [ "en" ], "patternProperties": { "^[a-z]{2}(-[A-Za-z]+)?$": { "type": "string", "pattern": "^manual\\.[a-z]{2}(-[A-Za-z]+)?\\.json$" } }, "additionalProperties": false }, "reference": { "const": "reference.json" }, "verification": { "enum": [ "verification.json", null ] }, "runtimes": { "type": "object", "required": [ "native" ], "additionalProperties": false, "properties": { "native": { "type": "object", "required": [ "file", "language", "python", "dependencies", "platforms" ], "additionalProperties": false, "properties": { "file": { "const": "runtime/controller.pyz" }, "language": { "const": "python" }, "python": { "type": "string" }, "dependencies": { "const": "runtime/requirements.txt" }, "platforms": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": [ "linux", "windows", "macos" ] } } } } } }, "capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": [ "rl_onnx", "ik_mocap", "wheeled_velocity", "cpg_keyframe", "model_viewer" ] } }, "source": { "type": "object", "required": [ "model_sha256" ], "additionalProperties": false, "properties": { "model_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "files": { "description": "Every file in the bundle but bundle.json itself, by its path inside it.", "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "required": [ "bytes", "sha256" ], "additionalProperties": false, "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } }, "licenses": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "description": "Inventoried platform and explicitly supplied asset/policy license and attribution files." } } } }, "oneOf": [ { "$ref": "#/$defs/policyBundle" }, { "$ref": "#/$defs/robotApp" } ] }