Files
SkillFactory/docs/schemas/part_spec.v2.schema.json
2026-10-10 16:34:40 +08:00

225 lines
11 KiB
JSON

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SkillFactory PartSpec v2 — body-part independent hardware contract",
"type": "object", "additionalProperties": false,
"required": ["schema_version", "kind", "part_id", "part_type", "description_role", "source", "topology", "frames", "root_frame", "attachment", "actuators", "end_effectors", "sensors", "timing", "safety", "scales"],
"properties": {
"schema_version": {"type": "integer", "const": 2},
"kind": {"const": "robot_part"},
"part_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
"part_type": {"enum": ["leg", "arm", "hand", "gripper", "torso", "neck", "head", "mobile_base", "sensor", "other"]},
"description_role": {"enum": ["asset_reference", "design_template"]},
"source": {
"type": "object", "additionalProperties": false,
"required": ["format", "root", "path", "package_name", "license_file", "license_id", "revision", "sha256"],
"properties": {
"format": {"enum": ["urdf", "usd", "mjcf", "design"]},
"root": {"type": ["string", "null"], "minLength": 1},
"path": {"type": ["string", "null"], "minLength": 1, "pattern": "^[^/]"},
"package_name": {"type": ["string", "null"], "minLength": 1},
"license_file": {"type": ["string", "null"], "minLength": 1},
"license_id": {"$ref": "#/$defs/text"},
"revision": {"type": ["string", "null"], "minLength": 1},
"sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}
}
},
"topology": {
"type": "object", "additionalProperties": false,
"required": ["structure", "root_body", "bodies", "joints", "constraints"],
"properties": {
"structure": {"enum": ["tree", "closed_chain"]},
"root_body": {"$ref": "#/$defs/local_id"},
"bodies": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/local_id"}},
"joints": {"type": "array", "items": {"$ref": "#/$defs/joint"}},
"constraints": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "type", "parent_frame", "child_frame"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "type": {"const": "loop_closure"},
"parent_frame": {"$ref": "#/$defs/local_id"}, "child_frame": {"$ref": "#/$defs/local_id"}
}
}
}
}
},
"frames": {
"type": "array", "minItems": 1, "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "body", "xyz", "quat_xyzw"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "body": {"$ref": "#/$defs/local_id"},
"xyz": {"$ref": "#/$defs/vector3"}, "quat_xyzw": {"$ref": "#/$defs/quaternion"}
}
}
},
"root_frame": {"$ref": "#/$defs/local_id"},
"attachment": {
"type": "object", "additionalProperties": false,
"required": ["mode", "frame_id", "source_mount_joint", "auxiliary_root_joints"],
"properties": {
"mode": {"enum": ["fixed", "floating", "external"]},
"frame_id": {"$ref": "#/$defs/local_id"},
"source_mount_joint": {"type": ["string", "null"], "minLength": 1},
"auxiliary_root_joints": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
"source_parent_transform": {
"type": "object", "additionalProperties": false, "required": ["body", "xyz", "quat_xyzw"],
"properties": {
"body": {"$ref": "#/$defs/text"}, "xyz": {"$ref": "#/$defs/vector3"},
"quat_xyzw": {"$ref": "#/$defs/quaternion"}
}
}
}
},
"actuators": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "joint_id", "neutral_position", "commands"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "joint_id": {"$ref": "#/$defs/local_id"},
"neutral_position": {"type": "number"},
"commands": {
"type": "object", "minProperties": 1, "additionalProperties": false,
"properties": {
"position_pd": {"$ref": "#/$defs/command"}, "position": {"$ref": "#/$defs/command"},
"velocity": {"$ref": "#/$defs/command"}, "effort": {"$ref": "#/$defs/command"}
}
}
}
}
},
"end_effectors": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "role", "frame_id", "contact"],
"properties": {
"id": {"$ref": "#/$defs/local_id"},
"role": {"enum": ["support", "tool", "fingertip", "grasp", "gaze", "sensor_mount", "other"]},
"frame_id": {"$ref": "#/$defs/local_id"},
"contact": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false,
"required": ["source_collision_index", "gap_method"],
"properties": {
"source_collision_index": {"type": "integer", "minimum": 0},
"gap_method": {"enum": ["sphere", "box", "mesh_distance", "none"]}
}
}
]
}
}
}
},
"sensors": {
"type": "array", "items": {
"type": "object", "additionalProperties": false,
"required": ["id", "kind", "outputs", "frame_id", "target", "update_period_s"],
"properties": {
"id": {"$ref": "#/$defs/local_id"},
"kind": {"enum": ["joint_state", "contact_normal", "wrench", "imu", "camera", "tactile", "lidar", "other"]},
"outputs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
"frame_id": {"$ref": "#/$defs/local_id"},
"target": {
"type": "object", "additionalProperties": false, "required": ["entity", "ids"],
"properties": {
"entity": {"enum": ["part", "joint", "end_effector"]},
"ids": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/local_id"}}
}
},
"update_period_s": {"type": "number", "exclusiveMinimum": 0}
}
}
},
"timing": {
"type": "object", "additionalProperties": false, "required": ["physics_dt_s", "control_dt_s"],
"properties": {
"physics_dt_s": {"type": ["number", "null"], "exclusiveMinimum": 0},
"control_dt_s": {"type": "number", "exclusiveMinimum": 0}
}
},
"safety": {
"type": "object", "additionalProperties": false,
"required": ["soft_limit_factor", "on_invalid_command", "on_timeout", "command_timeout_s"],
"properties": {
"soft_limit_factor": {"type": "number", "exclusiveMinimum": 0, "maximum": 1},
"on_invalid_command": {"const": "reject"},
"on_timeout": {"enum": ["hold", "zero_effort", "disable"]},
"command_timeout_s": {"type": "number", "exclusiveMinimum": 0}
}
},
"scales": {
"type": "object", "additionalProperties": false, "required": ["length_m", "known_mass_kg"],
"properties": {
"length_m": {"type": ["number", "null"], "exclusiveMinimum": 0},
"known_mass_kg": {"type": ["number", "null"], "exclusiveMinimum": 0}
}
},
"extensions": {"type": "object", "patternProperties": {"^[a-z][a-z0-9_]*\\.[a-z0-9_.]+$": {}}, "additionalProperties": false}
},
"allOf": [
{
"if": {"properties": {"description_role": {"const": "design_template"}}},
"then": {"properties": {"source": {"properties": {"format": {"const": "design"}, "root": {"type": "null"}, "path": {"type": "null"}, "package_name": {"type": "null"}, "license_file": {"type": "null"}, "revision": {"type": "null"}, "sha256": {"type": "null"}}}}},
"else": {"properties": {"source": {"properties": {"format": {"enum": ["urdf", "usd", "mjcf"]}, "root": {"type": "string"}, "path": {"type": "string"}, "license_file": {"type": "string"}}}}}
}
],
"$defs": {
"text": {"type": "string", "minLength": 1, "pattern": "\\S"},
"local_id": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"},
"vector3": {"type": "array", "minItems": 3, "maxItems": 3, "items": {"type": "number"}},
"quaternion": {"type": "array", "minItems": 4, "maxItems": 4, "items": {"type": "number"}},
"command": {
"type": "object", "additionalProperties": false, "required": ["unit", "scale", "offset", "gains"],
"properties": {
"unit": {"enum": ["rad", "m", "rad/s", "m/s", "N*m", "N"]},
"scale": {"type": "number", "exclusiveMinimum": 0}, "offset": {"type": "number"},
"gains": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["kp", "kd"],
"properties": {"kp": {"type": "number", "exclusiveMinimum": 0}, "kd": {"type": "number", "minimum": 0}}
}
]
}
}
},
"joint": {
"type": "object", "additionalProperties": false,
"required": ["id", "source_name", "type", "parent", "child", "origin", "actuation", "position_unit", "axis", "limits_origin", "limits", "coupling"],
"properties": {
"id": {"$ref": "#/$defs/local_id"}, "source_name": {"$ref": "#/$defs/text"},
"type": {"enum": ["fixed", "revolute", "continuous", "prismatic"]},
"parent": {"$ref": "#/$defs/local_id"}, "child": {"$ref": "#/$defs/local_id"},
"origin": {
"type": "object", "additionalProperties": false, "required": ["xyz", "quat_xyzw"],
"properties": {"xyz": {"$ref": "#/$defs/vector3"}, "quat_xyzw": {"$ref": "#/$defs/quaternion"}}
},
"actuation": {"enum": ["fixed", "active", "passive", "coupled"]},
"position_unit": {"enum": ["rad", "m", null]},
"axis": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/vector3"}]},
"limits_origin": {"enum": ["source", "declared"]},
"limits": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["position", "velocity", "effort"],
"properties": {
"position": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "number"}}]},
"velocity": {"type": "number", "exclusiveMinimum": 0}, "effort": {"type": "number", "exclusiveMinimum": 0}
}
}
]
},
"coupling": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["joint_id", "multiplier", "offset"],
"properties": {"joint_id": {"$ref": "#/$defs/local_id"}, "multiplier": {"type": "number"}, "offset": {"type": "number"}}
}
]
}
}
}
}
}