ModelAnalysisResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/smartcut-dev/json-schema/smartcut-dev-model-analysis-response-schema.json",
  "title": "ModelAnalysisResponse",
  "description": "The result of analysing a 3D model. `parts` is submittable to `/v3/calculate` unchanged.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/smartcut-dev-openapi-openapi.json#/components/schemas/ModelAnalysisResponse",
  "type": "object",
  "properties": {
    "version": {
      "type": "string",
      "enum": [
        "3"
      ]
    },
    "model": {
      "type": "object",
      "description": "What was read, and in what units.",
      "properties": {
        "format": {
          "type": [
            "string",
            "null"
          ],
          "description": "Detected format: `step`, `stl`, `obj`, `ply` or `gltf`."
        },
        "units": {
          "type": "string",
          "description": "The unit every number in this response is in."
        },
        "sourceUnits": {
          "type": "string",
          "description": "The unit the geometry was read as — your `sourceUnits`, else the file's own declaration, else `units`."
        },
        "declaredUnits": {
          "type": [
            "string",
            "null"
          ],
          "description": "The unit the FILE declared, where the format carries one (STEP, 3MF, Collada). Null otherwise."
        },
        "suggestedUnits": {
          "type": "string",
          "description": "A different `sourceUnits` that would make the model plausible against the `bladeWidth` you supplied. Only present when you supplied one and the current reading looks wrong."
        },
        "stats": {
          "type": "object",
          "properties": {
            "parts": {
              "type": "integer",
              "description": "Rows in `parts`."
            },
            "rectangular": {
              "type": "integer"
            },
            "irregular": {
              "type": "integer"
            },
            "unrecognised": {
              "type": "integer"
            },
            "fixtures": {
              "type": "integer",
              "description": "Parts judged to be fittings rather than sheet goods."
            },
            "merged": {
              "type": "integer",
              "description": "Identical parts collapsed into a quantity."
            },
            "triangles": {
              "type": "integer"
            },
            "components": {
              "type": "integer",
              "description": "Separate solids found in the file."
            },
            "debris": {
              "type": "integer",
              "description": "Fragments too small to be parts, ignored."
            },
            "modelDiagonal": {
              "type": "number",
              "description": "Bounding-box diagonal of the whole model, in `units`."
            },
            "modelSize": {
              "type": "object",
              "properties": {
                "x": {
                  "type": "number"
                },
                "y": {
                  "type": "number"
                },
                "z": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "required": [
        "format",
        "units",
        "sourceUnits",
        "declaredUnits",
        "stats"
      ]
    },
    "parts": {
      "type": "array",
      "description": "Parts, in `/v3/calculate`'s own vocabulary. Post this array back as that endpoint's `parts`.",
      "items": {
        "$ref": "#/$defs/ModelPart"
      }
    },
    "advice": {
      "type": "array",
      "description": "Everything the analysis knows that a calculation does not. Points at `parts` by index.",
      "items": {
        "$ref": "#/$defs/ModelAdvice"
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Notes from the file reader itself, e.g. that an STL carries no part names."
    }
  },
  "required": [
    "version",
    "model",
    "parts",
    "advice",
    "warnings"
  ],
  "$defs": {
    "ModelAdvice": {
      "type": "object",
      "description": "One thing worth knowing about the model or a part in it.",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable code, e.g. `open-mesh`, `fixture-detected`, `parts-overlap`, `squared-off-waste`, `dimensions-approximate`."
        },
        "severity": {
          "type": "string",
          "enum": [
            "info",
            "warning",
            "error"
          ],
          "description": "`error` means the part cannot be cut as measured."
        },
        "message": {
          "type": "string"
        },
        "partIndex": {
          "type": "integer",
          "description": "Index into `parts`. Absent for advice about the file as a whole."
        },
        "otherPartIndex": {
          "type": "integer",
          "description": "The second part, for advice about a PAIR (overlaps)."
        },
        "penetrationFraction": {
          "type": "number",
          "description": "How deeply two parts overlap, as a fraction of the smaller part's smallest dimension."
        },
        "wastePct": {
          "type": "number",
          "description": "Fraction of the bounding rectangle that is waste, 0..1 — what nesting this part would save."
        },
        "confidence": {
          "type": "number",
          "description": "How sure the role verdict was, 0..1."
        }
      },
      "required": [
        "code",
        "severity",
        "message"
      ]
    },
    "ModelPart": {
      "type": "object",
      "description": "A part as the analyser found it. Every field except `role` is a `/v3/calculate` part field; `role` is ignored there, so the object can be submitted as-is.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Part name, from the model where it had one."
        },
        "l": {
          "type": "number",
          "description": "Length — the long side."
        },
        "w": {
          "type": "number",
          "description": "Width — the short side."
        },
        "t": {
          "type": "number",
          "description": "Thickness."
        },
        "q": {
          "type": "integer",
          "description": "Quantity. Above 1 when identical copies were merged into one row."
        },
        "material": {
          "type": "string",
          "description": "Material name read from the model, or empty when the file carried none."
        },
        "outline": {
          "type": "array",
          "description": "Closed polygon outline. Present for shaped parts — send it to a nesting model to keep the shape.",
          "items": {
            "type": "object",
            "properties": {
              "x": {
                "type": "number"
              },
              "y": {
                "type": "number"
              }
            }
          }
        },
        "holes": {
          "type": "array",
          "description": "Inner rings that are SHAPE — slots, cut-outs — in the outline's own frame. A ROUND ring is drilling rather than shape and comes back in `machining.holes` instead; nothing appears in both, so a part is never drilled and cut for the same hole.",
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "x": {
                  "type": "number"
                },
                "y": {
                  "type": "number"
                }
              }
            }
          }
        },
        "machining": {
          "type": "object",
          "description": "Machining read off the model, in `/v3/calculate`'s own `machining` shape — post it back untouched.",
          "properties": {
            "holes": {
              "type": "array",
              "description": "Round holes found in the part. Through holes, so `depth` is absent; measurements are in the response's `units`.",
              "items": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "number",
                    "description": "X of the hole centre, from the left edge."
                  },
                  "y": {
                    "type": "number",
                    "description": "Y of the hole centre, from the bottom edge."
                  },
                  "diameter": {
                    "type": "number",
                    "description": "Hole diameter."
                  },
                  "depth": {
                    "type": "number",
                    "description": "Hole depth. Absent for a through hole, which is what the analysis always finds."
                  },
                  "face": {
                    "type": "number",
                    "enum": [
                      0,
                      1
                    ],
                    "description": "Face index (0=front, 1=back)."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "regular",
                      "hinge",
                      "shelf"
                    ],
                    "description": "Hole type."
                  }
                },
                "required": [
                  "x",
                  "y",
                  "diameter"
                ]
              }
            }
          }
        },
        "role": {
          "type": "string",
          "enum": [
            "rect",
            "nesting",
            "fixture"
          ],
          "description": "What the part is FOR: a plain rectangle, a shape worth nesting, or a fitting that was never cut from sheet. Drop `fixture` rows before cutting. Ignored by `/v3/calculate`."
        }
      },
      "required": [
        "name",
        "l",
        "w",
        "t",
        "q",
        "material",
        "role"
      ]
    }
  }
}