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

142 lines
7.5 KiB
JSON

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SkillFactory SoftwareSpec v2 — capability-negotiated body-part ports",
"type": "object", "additionalProperties": false,
"required": ["schema_version", "kind", "software_id", "software_version", "status", "binding_mode", "hardware_bindings", "requirements", "interface", "runtime", "artifact"],
"properties": {
"schema_version": {"type": "integer", "const": 2},
"kind": {"const": "part_software"},
"software_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
"software_version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
"status": {"enum": ["design", "prototype"]},
"binding_mode": {"const": "alternatives"},
"hardware_bindings": {
"type": "array", "minItems": 1, "uniqueItems": true, "items": {
"type": "object", "additionalProperties": false, "required": ["part_id", "spec_path"],
"properties": {
"part_id": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
"spec_path": {"$ref": "#/$defs/repo_path"}
}
}
},
"requirements": {
"type": "object", "additionalProperties": false,
"required": ["part_types", "joint_types", "topologies", "attachment_modes", "supports_coupling", "required_control_modes", "required_sensor_kinds", "required_sensor_outputs", "required_effector_roles", "capacities"],
"properties": {
"part_types": {"$ref": "#/$defs/names"},
"joint_types": {"type": "array", "uniqueItems": true, "items": {"enum": ["revolute", "continuous", "prismatic"]}},
"topologies": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["tree", "closed_chain"]}},
"attachment_modes": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["fixed", "floating", "external"]}},
"supports_coupling": {"type": "boolean"},
"required_control_modes": {"type": "array", "uniqueItems": true, "items": {"enum": ["position_pd", "position", "velocity", "effort"]}},
"required_sensor_kinds": {"$ref": "#/$defs/names"},
"required_sensor_outputs": {"$ref": "#/$defs/names"},
"required_effector_roles": {"$ref": "#/$defs/names"},
"capacities": {
"type": "object", "additionalProperties": false, "required": ["Jmax", "Amax", "Emax", "Smax"],
"properties": {
"Jmax": {"type": "integer", "minimum": 0}, "Amax": {"type": "integer", "minimum": 0},
"Emax": {"type": "integer", "minimum": 0}, "Smax": {"type": "integer", "minimum": 0}
}
}
}
},
"interface": {
"type": "object", "additionalProperties": false,
"required": ["contract_id", "contract_version", "quaternion_order", "ports", "reset", "action_history"],
"properties": {
"contract_id": {"$ref": "#/$defs/id"},
"contract_version": {"type": "integer", "minimum": 1},
"quaternion_order": {"const": "xyzw"},
"ports": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/port"}},
"reset": {"enum": ["indexed_isolated", "not_applicable"]},
"action_history": {"enum": ["last_applied", "none"]}
}
},
"runtime": {
"type": "object", "additionalProperties": false,
"required": ["adapter_id", "implementation", "dependencies", "devices", "timing"],
"properties": {
"adapter_id": {"type": ["string", "null"], "minLength": 1},
"implementation": {"enum": ["available", "unimplemented"]},
"dependencies": {"type": "object", "additionalProperties": {"type": "string", "minLength": 1}},
"devices": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["cpu", "cuda"]}},
"timing": {
"type": "object", "additionalProperties": false, "required": ["policy", "control_dt_s"],
"properties": {
"policy": {"enum": ["common_control_dt", "per_part"]},
"control_dt_s": {"type": ["number", "null"], "exclusiveMinimum": 0}
}
}
}
},
"artifact": {
"type": "object", "additionalProperties": false,
"required": ["format", "checkpoint", "trained_skill", "frozen"],
"properties": {
"format": {"type": "string", "minLength": 1},
"checkpoint": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["path", "sha256"],
"properties": {"path": {"$ref": "#/$defs/repo_path"}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}
}
]
},
"trained_skill": {"const": false}, "frozen": {"const": false}
}
},
"extensions": {"type": "object", "patternProperties": {"^[a-z][a-z0-9_]*\\.[a-z0-9_.]+$": {}}, "additionalProperties": false}
},
"$defs": {
"id": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"},
"text": {"type": "string", "minLength": 1, "pattern": "\\S"},
"names": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/text"}},
"repo_path": {"type": "string", "pattern": "^(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_.-]+$"},
"selector": {
"type": "object", "additionalProperties": false, "required": ["type", "values"],
"properties": {"type": {"enum": ["all", "ids", "role", "sensor_kind", "sensor_output"]}, "values": {"$ref": "#/$defs/names"}}
},
"feature": {
"type": "object", "additionalProperties": false, "required": ["name", "quantity", "unit", "normalization"],
"properties": {
"name": {"$ref": "#/$defs/id"}, "quantity": {"$ref": "#/$defs/text"},
"unit": {"enum": ["1", "m", "s", "kg", "rad", "m/s", "rad/s", "m/s^2", "rad/s^2", "N", "N*m", "kg*m^2", "N*m/rad", "N*m*s/rad", "N/m", "N*s/m", "joint_position", "joint_velocity", "joint_effort", "actuator_command"]},
"normalization": {"$ref": "#/$defs/text"}
}
},
"port": {
"type": "object", "additionalProperties": false,
"required": ["name", "direction", "kind", "entity", "selector", "required", "dtype", "shape", "frame", "representation", "features", "mask", "command"],
"properties": {
"name": {"$ref": "#/$defs/id"}, "direction": {"enum": ["input", "output"]},
"kind": {"enum": ["description", "state", "mask", "goal", "command", "context", "image"]},
"entity": {"enum": ["part", "joint", "actuator", "end_effector", "sensor"]},
"selector": {"$ref": "#/$defs/selector"}, "required": {"type": "boolean"},
"dtype": {"enum": ["float32", "bool", "uint8", "int64"]},
"shape": {
"type": "array", "minItems": 1, "items": {
"oneOf": [{"type": "integer", "minimum": 1}, {"enum": ["B", "Jmax", "Amax", "Emax", "Smax"]}]
}
},
"frame": {"enum": ["part_root", "world", "entity", "none"]},
"representation": {"enum": ["features", "tensor"]},
"features": {"type": "array", "items": {"$ref": "#/$defs/feature"}},
"mask": {"type": ["string", "null"], "pattern": "^[A-Za-z][A-Za-z0-9_]*$"},
"command": {
"oneOf": [
{"type": "null"},
{"type": "object", "additionalProperties": false, "required": ["mode", "encoding", "clip"],
"properties": {
"mode": {"enum": ["position_pd", "position", "velocity", "effort"]},
"encoding": {"enum": ["normalized", "physical"]},
"clip": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "number"}}]}
}
}
]
}
}
}
}
}