cadSet/designir-pipeline/contracts/assembly-designir-1.0.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cadset.local/contracts/assembly-designir-1.0.schema.json",
  "title": "Assembly DesignIR 1.0",
  "description": "Coordinate-free semantic structure, mating, kinematics and transmission contract.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "designir_kind",
    "model_id",
    "family",
    "units",
    "parameters",
    "modules",
    "components",
    "relations",
    "kinematics",
    "edit_interface",
    "validation_contract"
  ],
  "properties": {
    "schema_version": {
      "const": "assembly-1.0"
    },
    "designir_kind": {
      "const": "coordinate_free_semantic_assembly"
    },
    "model_id": {
      "$ref": "#/$defs/identifier"
    },
    "family": {
      "$ref": "#/$defs/identifier"
    },
    "units": {
      "enum": ["mm", "inch"]
    },
    "design_intent": {
      "type": "string",
      "minLength": 1
    },
    "parameters": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/parameter"
      }
    },
    "expressions": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "minLength": 1
      }
    },
    "modules": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/module"
      }
    },
    "components": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/component"
      }
    },
    "relations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/relation"
      }
    },
    "kinematics": {
      "$ref": "#/$defs/kinematics"
    },
    "edit_interface": {
      "$ref": "#/$defs/editInterface"
    },
    "validation_contract": {
      "$ref": "#/$defs/validationContract"
    }
  },
  "$defs": {
    "identifier": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*$"
    },
    "parameter": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "value", "editable"],
      "properties": {
        "kind": {
          "enum": ["length", "angle", "ratio", "count", "mass", "torque", "speed", "scalar", "choice", "boolean"]
        },
        "value": {},
        "unit": {
          "type": "string"
        },
        "editable": {
          "type": "boolean"
        },
        "bounds": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": "number"
          }
        },
        "choices": {
          "type": "array",
          "items": {}
        },
        "description": {
          "type": "string"
        },
        "status": {
          "enum": ["specified", "inferred", "estimated", "derived"]
        }
      }
    },
    "module": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "purpose", "members"],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "purpose": {
          "type": "string",
          "minLength": 1
        },
        "members": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "replaceable_as_unit": {
          "type": "boolean"
        }
      }
    },
    "component": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "role",
        "archetype",
        "lifecycle",
        "generation",
        "interfaces"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "role": {
          "$ref": "#/$defs/identifier"
        },
        "archetype": {
          "$ref": "#/$defs/identifier"
        },
        "lifecycle": {
          "enum": ["required", "optional", "replaceable", "generated_pattern"]
        },
        "quantity": {
          "oneOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "minLength": 1
            }
          ]
        },
        "generation": {
          "type": "object",
          "additionalProperties": false,
          "required": ["strategy", "family", "parameter_bindings"],
          "properties": {
            "strategy": {
              "enum": ["semantic_feature_program", "standard_library", "supplier_catalog", "subassembly_template"]
            },
            "family": {
              "$ref": "#/$defs/identifier"
            },
            "parameter_bindings": {
              "type": "object",
              "additionalProperties": {
                "type": ["string", "number", "integer", "boolean"]
              }
            }
          }
        },
        "interfaces": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/interface"
          }
        },
        "material_class": {
          "$ref": "#/$defs/identifier"
        },
        "tags": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        }
      }
    },
    "interface": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "type", "construction"],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "type": {
          "enum": ["axis", "plane", "cylinder", "hole_pattern", "shaft_seat", "bearing_seat", "fastener_seat", "torque_interface", "contact_envelope"]
        },
        "construction": {
          "enum": ["primary_axis", "secondary_axis", "front_axial_face", "rear_axial_face", "inner_cylindrical_surface", "outer_cylindrical_surface", "pitch_circle_pattern", "shoulder_face", "center_plane", "generated_feature"]
        },
        "qualifiers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "parameter_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        }
      }
    },
    "endpoint": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"
    },
    "relation": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "type", "a", "b", "intent"],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "type": {
          "enum": ["coaxial", "face_mate", "face_offset", "parallel", "perpendicular", "insert", "bearing_support", "axial_capture", "fasten_pattern", "torque_lock", "radial_clearance", "axial_clearance", "tangent"]
        },
        "a": {
          "$ref": "#/$defs/endpoint"
        },
        "b": {
          "$ref": "#/$defs/endpoint"
        },
        "intent": {
          "type": "string",
          "minLength": 1
        },
        "value": {
          "oneOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "minLength": 1
            }
          ]
        },
        "tolerance": {
          "oneOf": [
            {
              "type": "number",
              "minimum": 0
            },
            {
              "type": "string",
              "minLength": 1
            }
          ]
        },
        "mobility": {
          "enum": ["fixed", "allow_rotation", "allow_translation", "allow_rotation_and_translation"]
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "kinematics": {
      "type": "object",
      "additionalProperties": false,
      "required": ["anchor_component", "rigid_groups", "joints", "transmissions"],
      "properties": {
        "anchor_component": {
          "$ref": "#/$defs/identifier"
        },
        "rigid_groups": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "members"],
            "properties": {
              "id": {
                "$ref": "#/$defs/identifier"
              },
              "members": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "$ref": "#/$defs/identifier"
                }
              }
            }
          }
        },
        "joints": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "type", "parent_group", "child_group", "axis_ref", "station_ref"],
            "properties": {
              "id": {
                "$ref": "#/$defs/identifier"
              },
              "type": {
                "enum": ["fixed", "revolute", "continuous", "prismatic", "cylindrical"]
              },
              "parent_group": {
                "$ref": "#/$defs/identifier"
              },
              "child_group": {
                "$ref": "#/$defs/identifier"
              },
              "axis_ref": {
                "$ref": "#/$defs/endpoint"
              },
              "station_ref": {
                "$ref": "#/$defs/endpoint"
              },
              "dynamics": {
                "type": "object",
                "additionalProperties": {
                  "type": ["number", "string"]
                }
              }
            }
          }
        },
        "transmissions": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "type", "input_joint", "output_joint", "ratio_expression"],
            "properties": {
              "id": {
                "$ref": "#/$defs/identifier"
              },
              "type": {
                "enum": ["direct", "gear_pair", "planetary", "harmonic", "cycloidal", "belt", "chain", "screw"]
              },
              "input_joint": {
                "$ref": "#/$defs/identifier"
              },
              "output_joint": {
                "$ref": "#/$defs/identifier"
              },
              "ratio_expression": {
                "type": "string",
                "minLength": 1
              },
              "fixed_member": {
                "$ref": "#/$defs/identifier"
              },
              "compliance_model": {
                "$ref": "#/$defs/identifier"
              }
            }
          }
        }
      }
    },
    "editInterface": {
      "type": "object",
      "additionalProperties": false,
      "required": ["editable_parameters", "structural_operations", "preserved_interfaces"],
      "properties": {
        "editable_parameters": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/identifier"
          }
        },
        "structural_operations": {
          "type": "array",
          "items": {
            "enum": ["add_component", "remove_component", "replace_component", "change_relation", "change_transmission", "add_module"]
          }
        },
        "preserved_interfaces": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/endpoint"
          }
        }
      }
    },
    "validationContract": {
      "type": "object",
      "additionalProperties": false,
      "required": ["coordinate_free_source", "required_checks"],
      "properties": {
        "coordinate_free_source": {
          "const": true
        },
        "required_checks": {
          "type": "array",
          "minItems": 1,
          "items": {
            "enum": ["schema_valid", "reference_integrity", "constraint_graph_connected", "assembly_solvable_from_scrambled_state", "no_overconstraint", "interface_compatibility", "clearance", "interference", "joint_mobility", "parameter_perturbation", "preserved_interface", "urdf_load", "mjcf_load"]
          }
        },
        "acceptance_rules": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}