madoo.subject-location/v1

Madoo subject location — Where Locate Subject found the subject of the reference pictures (or of the description) in a picture: its box and the crop region framed around it, its share of the picture, the edges it touches, whether it was ambiguous and the other candidates. A prediction, not a measurement.

Reference	madoo.subject-location/v1
Schema id	urn:madoo:schema:subject-location:v1
Version	1.0.0
Served at	GET /api/v1/json-schemas/madoo.subject-location/v1 · MCP get_json_schema

Where it appears

• Produced by: ai/locate_subject → subject

Fields

Field	Type	Required	Rules	Description
schema	"madoo.subject-location/v1"	yes
image	object	yes	no other fields
image.width	integer	yes	≥ 1	Width of the upright picture, in pixels.
image.height	integer	yes	≥ 1	Height of the upright picture, in pixels.
model	string	yes		The model that located the subject.
settings	object	yes	no other fields
settings.framing	one of "subject", "context"	yes
settings.margin	number	yes	≥ 0; ≤ 0.5
settings.aspect	one of "none", "1:1", "4:5", "3:4", "2:3", "9:16", "5:4", "4:3", "3:2", "16:9"	yes
settings.references	integer	yes	≥ 0; ≤ 6	How many reference pictures were sent.
settings.described	boolean	yes		Whether a description was sent.
found	boolean	yes
ambiguous	boolean	yes		Several objects could be the subject: the largest was taken, the others are in candidates.
subject	object or null	yes
candidates	array of objects	yes		The other objects that could be the subject, when the answer was ambiguous.
candidates[].x	integer	yes	≥ 0
candidates[].y	integer	yes	≥ 0
candidates[].width	integer	yes	≥ 1
candidates[].height	integer	yes	≥ 1
crop_region	object or null	yes		The rectangle cut as the crop, ready for Crop’s region; null when the subject was not found.

The complete schema

madoo.subject-location/v1 (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:madoo:schema:subject-location:v1",
  "title": "Madoo subject location",
  "description": "What Locate Subject (ai/locate_subject) found: where the subject of the reference pictures (or of the description) is in a picture — its box and the crop region framed around it, in pixels of the upright picture —, how much of the picture it covers, the edges it touches, whether it was ambiguous and the other candidates, and the model that answered. A model's prediction, not a measurement; it locates the subject and does not judge whether it is faithful.",
  "type": "object",
  "required": [
    "schema",
    "image",
    "model",
    "settings",
    "found",
    "ambiguous",
    "subject",
    "candidates",
    "crop_region"
  ],
  "additionalProperties": false,
  "properties": {
    "schema": {
      "const": "madoo.subject-location/v1"
    },
    "image": {
      "type": "object",
      "required": [
        "width",
        "height"
      ],
      "additionalProperties": false,
      "properties": {
        "width": {
          "type": "integer",
          "minimum": 1,
          "description": "Width of the upright picture, in pixels."
        },
        "height": {
          "type": "integer",
          "minimum": 1,
          "description": "Height of the upright picture, in pixels."
        }
      }
    },
    "model": {
      "type": "string",
      "description": "The model that located the subject."
    },
    "settings": {
      "type": "object",
      "required": [
        "framing",
        "margin",
        "aspect",
        "references",
        "described"
      ],
      "additionalProperties": false,
      "properties": {
        "framing": {
          "enum": [
            "subject",
            "context"
          ]
        },
        "margin": {
          "type": "number",
          "minimum": 0,
          "maximum": 0.5
        },
        "aspect": {
          "enum": [
            "none",
            "1:1",
            "4:5",
            "3:4",
            "2:3",
            "9:16",
            "5:4",
            "4:3",
            "3:2",
            "16:9"
          ]
        },
        "references": {
          "type": "integer",
          "minimum": 0,
          "maximum": 6,
          "description": "How many reference pictures were sent."
        },
        "described": {
          "type": "boolean",
          "description": "Whether a description was sent."
        }
      }
    },
    "found": {
      "type": "boolean"
    },
    "ambiguous": {
      "type": "boolean",
      "description": "Several objects could be the subject: the largest was taken, the others are in candidates."
    },
    "subject": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "box",
            "area_proportion",
            "touches_edges",
            "crop_complete"
          ],
          "additionalProperties": false,
          "properties": {
            "box": {
              "$ref": "#/$defs/rect",
              "description": "The subject's box, the whole object."
            },
            "area_proportion": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Share of the picture the box covers."
            },
            "touches_edges": {
              "type": "array",
              "items": {
                "enum": [
                  "top",
                  "right",
                  "bottom",
                  "left"
                ]
              },
              "description": "The edges of the picture the box reaches: the subject may be cut there."
            },
            "crop_complete": {
              "type": "boolean",
              "description": "Whether the crop region holds the whole framing asked for (false when the picture's edges cut it)."
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "candidates": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/rect"
      },
      "description": "The other objects that could be the subject, when the answer was ambiguous."
    },
    "crop_region": {
      "oneOf": [
        {
          "$ref": "#/$defs/rect"
        },
        {
          "type": "null"
        }
      ],
      "description": "The rectangle cut as the crop, ready for Crop's region; null when the subject was not found."
    }
  },
  "$defs": {
    "rect": {
      "type": "object",
      "required": [
        "x",
        "y",
        "width",
        "height"
      ],
      "additionalProperties": false,
      "properties": {
        "x": {
          "type": "integer",
          "minimum": 0
        },
        "y": {
          "type": "integer",
          "minimum": 0
        },
        "width": {
          "type": "integer",
          "minimum": 1
        },
        "height": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  }
}