Docs / Schemas / object-detection

Object Detection 0.8.0

Represent objects detected within a source. Supports bounding boxes, polygons, hierarchical relationships, and confidence scores.

$id

https://oatschema.org/0.8.0/object-detection

Latest

https://oatschema.org/object-detection

Versions

Source

v0.8.0 on GitHub

Schema

object-detection.json Raw

{    "x-license": {        "id": "Apache-2.0",        "notice": "Copyright 2025-2026 The OATS Authors",        "url": "https://github.com/oatschema/oats/blob/main/LICENSE"    },    "$schema": "https://json-schema.org/draft/2020-12/schema",    "$id": "https://oatschema.org/0.8.0/object-detection",    "title": "Object Detection",    "x-version": "0.8.0",    "description": "Represent objects detected within a source. Supports bounding boxes, polygons, hierarchical relationships, and confidence scores.",    "type": "object",    "properties": {        "unit": {            "type": "string",            "description": "The unit for all coordinate values: 'px' for pixels, 'pt' for typographic points, 'normalized' for values from 0.0 to 1.0, and 'per_mille' for values from 0 to 1000. Required whenever geometric data is present.",            "enum": [                "px",                "pt",                "normalized",                "per_mille"            ]        },        "producer": {            "type": "string",            "description": "The creator (model, tool or author) of this record.",            "maxLength": 1024        },        "vocabulary_url": {            "type": "string",            "description": "A URL pointing to a more detailed external vocabulary or ontology.",            "format": "uri",            "maxLength": 2048        },        "vocabulary": {            "type": "array",            "description": "A list of the possible labels for detected objects. For more than 100 labels, use 'vocabulary_url'.",            "maxItems": 100,            "uniqueItems": true,            "items": {                "type": "string",                "description": "A single valid label from the vocabulary.",                "maxLength": 128            }        },        "score_explanation": {            "type": "string",            "description": "Defines the meaning and range of the 'score' field.",            "maxLength": 256        },        "objects": {            "type": "array",            "description": "The detected objects.",            "maxItems": 100000,            "items": {                "type": "object",                "description": "A single detected object.",                "properties": {                    "id": {                        "type": "string",                        "description": "A unique identifier for this object within this record (e.g., UUID4). Required for establishing hierarchies.",                        "maxLength": 128                    },                    "parent_id": {                        "type": "string",                        "description": "The id of the parent object, if this object is nested within another.",                        "maxLength": 128                    },                    "label": {                        "type": "string",                        "description": "The label of the detected object (e.g., 'car', 'face', 'logo'). Must be a member of 'vocabulary' when it is present.",                        "maxLength": 128                    },                    "score": {                        "type": "number",                        "description": "A normalized score for this detection (-1.0 to 1.0). Positive values [0, 1] represent confidence in the object's presence. Negative values [-1, 0) are reserved for 'hard negatives' (e.g., explicitly marking that an object is not present in this region).",                        "minimum": -1,                        "maximum": 1                    },                    "box": {                        "type": "object",                        "description": "A rectangular bounding box defined by its top-left corner (x, y) and its dimensions.",                        "properties": {                            "x": {                                "type": "number",                                "description": "The x-coordinate of the top-left corner.",                                "minimum": 0                            },                            "y": {                                "type": "number",                                "description": "The y-coordinate of the top-left corner.",                                "minimum": 0                            },                            "width": {                                "type": "number",                                "description": "The width of the box.",                                "minimum": 0                            },                            "height": {                                "type": "number",                                "description": "The height of the box.",                                "minimum": 0                            }                        },                        "required": [                            "x",                            "y",                            "width",                            "height"                        ],                        "additionalProperties": false                    },                    "polygon": {                        "type": "array",                        "description": "An ordered list of vertices defining a non-rectangular boundary.",                        "minItems": 3,                        "maxItems": 1000,                        "items": {                            "type": "object",                            "description": "A single vertex, measured from the top-left corner of the page or image.",                            "properties": {                                "x": {                                    "type": "number",                                    "description": "The x-coordinate of the vertex.",                                    "minimum": 0                                },                                "y": {                                    "type": "number",                                    "description": "The y-coordinate of the vertex.",                                    "minimum": 0                                }                            },                            "required": [                                "x",                                "y"                            ],                            "additionalProperties": false                        }                    },                    "multi_polygon": {                        "type": "array",                        "description": "A list of polygons, for a single region that is occluded or fragmented into multiple visible parts.",                        "minItems": 1,                        "maxItems": 100,                        "items": {                            "type": "array",                            "description": "An ordered list of vertices defining a non-rectangular boundary.",                            "minItems": 3,                            "maxItems": 1000,                            "items": {                                "type": "object",                                "description": "A single vertex, measured from the top-left corner of the page or image.",                                "properties": {                                    "x": {                                        "type": "number",                                        "description": "The x-coordinate of the vertex.",                                        "minimum": 0                                    },                                    "y": {                                        "type": "number",                                        "description": "The y-coordinate of the vertex.",                                        "minimum": 0                                    }                                },                                "required": [                                    "x",                                    "y"                                ],                                "additionalProperties": false                            }                        }                    },                    "attributes": {                        "type": "object",                        "description": "Arbitrary metadata relevant to this item.",                        "maxProperties": 16,                        "propertyNames": {                            "maxLength": 128                        },                        "additionalProperties": {                            "anyOf": [                                {                                    "type": "string",                                    "maxLength": 1024                                },                                {                                    "type": "number"                                },                                {                                    "type": "boolean"                                },                                {                                    "type": "null"                                }                            ]                        }                    }                },                "required": [                    "label"                ],                "oneOf": [                    {                        "required": [                            "box"                        ]                    },                    {                        "required": [                            "polygon"                        ]                    },                    {                        "required": [                            "multi_polygon"                        ]                    }                ],                "additionalProperties": false            }        },        "attributes": {            "type": "object",            "description": "Arbitrary metadata relevant to this record.",            "maxProperties": 16,            "propertyNames": {                "maxLength": 128            },            "additionalProperties": {                "anyOf": [                    {                        "type": "string",                        "maxLength": 1024                    },                    {                        "type": "number"                    },                    {                        "type": "boolean"                    },                    {                        "type": "null"                    }                ]            }        }    },    "required": [        "unit",        "objects"    ],    "allOf": [        {            "if": {                "properties": {                    "unit": {                        "const": "normalized"                    }                },                "required": [                    "unit"                ]            },            "then": {                "properties": {                    "objects": {                        "items": {                            "properties": {                                "box": {                                    "properties": {                                        "x": {                                            "maximum": 1                                        },                                        "y": {                                            "maximum": 1                                        },                                        "width": {                                            "maximum": 1                                        },                                        "height": {                                            "maximum": 1                                        }                                    }                                },                                "polygon": {                                    "items": {                                        "properties": {                                            "x": {                                                "maximum": 1                                            },                                            "y": {                                                "maximum": 1                                            }                                        }                                    }                                },                                "multi_polygon": {                                    "items": {                                        "items": {                                            "properties": {                                                "x": {                                                    "maximum": 1                                                },                                                "y": {                                                    "maximum": 1                                                }                                            }                                        }                                    }                                }                            }                        }                    }                }            }        },        {            "if": {                "properties": {                    "unit": {                        "const": "per_mille"                    }                },                "required": [                    "unit"                ]            },            "then": {                "properties": {                    "objects": {                        "items": {                            "properties": {                                "box": {                                    "properties": {                                        "x": {                                            "maximum": 1000                                        },                                        "y": {                                            "maximum": 1000                                        },                                        "width": {                                            "maximum": 1000                                        },                                        "height": {                                            "maximum": 1000                                        }                                    }                                },                                "polygon": {                                    "items": {                                        "properties": {                                            "x": {                                                "maximum": 1000                                            },                                            "y": {                                                "maximum": 1000                                            }                                        }                                    }                                },                                "multi_polygon": {                                    "items": {                                        "items": {                                            "properties": {                                                "x": {                                                    "maximum": 1000                                                },                                                "y": {                                                    "maximum": 1000                                                }                                            }                                        }                                    }                                }                            }                        }                    }                }            }        }    ],    "additionalProperties": false}

Examples

Records that pass validation against this schema.

object-detection-2

object-detection-2.json

{  "unit": "per_mille",  "producer": "Manual Review",  "score_explanation": "Reviewer confidence, where 1.0 is certain.",  "vocabulary_url": "https://example.com/vocab/vehicles",  "objects": [    {      "id": "obj_1",      "label": "car",      "score": 1.0,      "multi_polygon": [        [          { "x": 100, "y": 400 },          { "x": 300, "y": 400 },          { "x": 300, "y": 600 }        ],        [          { "x": 350, "y": 420 },          { "x": 450, "y": 420 },          { "x": 450, "y": 600 }        ]      ]    },    {      "id": "obj_2",      "parent_id": "obj_1",      "label": "wheel",      "box": { "x": 120, "y": 540, "width": 60, "height": 60 }    }  ]}

object-detection-1

object-detection-1.json

{  "unit": "px",  "score_explanation": "Detector confidence probability.",  "objects": [    {      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",      "label": "car",      "score": 0.98,      "box": {        "x": 150,        "y": 200,        "width": 450,        "height": 200      }    },    {      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",      "parent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",      "label": "face",      "score": 0.85,      "polygon": [        { "x": 350, "y": 220 },        { "x": 390, "y": 225 },        { "x": 385, "y": 270 },        { "x": 345, "y": 265 }      ]    },    {      "id": "7b3dcb6d-2b0d-4bad-9b1d-eb4d3b7d4bad",      "parent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",      "label": "tire",      "score": 0.92,      "box": {        "x": 180,        "y": 350,        "width": 75,        "height": 75      }    },    {      "id": "3b7d4bad-9b1d-4bbf-b9d6-bcdbbfd4b2d9",      "parent_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",      "label": "tire",      "score": 0.91,      "box": {        "x": 480,        "y": 350,        "width": 75,        "height": 75      }    }  ]}

Fields

unit string required

The unit for all coordinate values: 'px' for pixels, 'pt' for typographic points, 'normalized' for values from 0.0 to 1.0, and 'per_mille' for values from 0 to 1000. Required whenever geometric data is present.
Allowed values: "px", "pt", "normalized", "per_mille"
producer string

The creator (model, tool or author) of this record.
- at most 1024 characters
vocabulary_url string

A URL pointing to a more detailed external vocabulary or ontology.
- at most 2048 characters
- format uri
vocabulary array of string

A list of the possible labels for detected objects. For more than 100 labels, use 'vocabulary_url'.
Each item: A single valid label from the vocabulary.
- at most 100 items
- items must be unique
- each at most 128 characters
score_explanation string

Defines the meaning and range of the 'score' field.
- at most 256 characters
objects array of object required

The detected objects.
Each item: A single detected object.
- at most 100000 items
- id string
  
  A unique identifier for this object within this record (e.g., UUID4). Required for establishing hierarchies.
  - at most 128 characters
- parent_id string
  
  The id of the parent object, if this object is nested within another.
  - at most 128 characters
- label string required
  
  The label of the detected object (e.g., 'car', 'face', 'logo'). Must be a member of 'vocabulary' when it is present.
  - at most 128 characters
- score number
  
  A normalized score for this detection (-1.0 to 1.0). Positive values [0, 1] represent confidence in the object's presence. Negative values [-1, 0) are reserved for 'hard negatives' (e.g., explicitly marking that an object is not present in this region).
  - -1 to 1
- box object
  
  A rectangular bounding box defined by its top-left corner (x, y) and its dimensions.
  - x number required
    
    The x-coordinate of the top-left corner.
    - ≥ 0
  - y number required
    
    The y-coordinate of the top-left corner.
    - ≥ 0
  - width number required
    
    The width of the box.
    - ≥ 0
  - height number required
    
    The height of the box.
    - ≥ 0
- polygon array of object
  
  An ordered list of vertices defining a non-rectangular boundary.
  Each item: A single vertex, measured from the top-left corner of the page or image.
  - 3 to 1000 items
  - x number required
    
    The x-coordinate of the vertex.
    - ≥ 0
  - y number required
    
    The y-coordinate of the vertex.
    - ≥ 0
- multi_polygon array of array of object
  
  A list of polygons, for a single region that is occluded or fragmented into multiple visible parts.
  Each item: An ordered list of vertices defining a non-rectangular boundary.
  - 1 to 100 items
  - each 3 to 1000 items
  - x number required
    
    The x-coordinate of the vertex.
    - ≥ 0
  - y number required
    
    The y-coordinate of the vertex.
    - ≥ 0
- attributes object
  
  Arbitrary metadata relevant to this item.
  - at most 16 properties
  - keys at most 128 characters
  - * string | number | boolean | null
    
    Any other key.
    - string: at most 1024 characters
Rules:
- Exactly one of box, polygon, multi_polygon must be present.
  Show the JSON Schema
```
{  "oneOf": [    {      "required": [        "box"      ]    },    {      "required": [        "polygon"      ]    },    {      "required": [        "multi_polygon"      ]    }  ]}
```
attributes object

Arbitrary metadata relevant to this record.
- at most 16 properties
- keys at most 128 characters
- * string | number | boolean | null
  
  Any other key.
  - string: at most 1024 characters

Rules:

When unit is "normalized", further limits apply.

Show the JSON Schema

{  "if": {    "properties": {      "unit": {        "const": "normalized"      }    },    "required": [      "unit"    ]  },  "then": {    "properties": {      "objects": {        "items": {          "properties": {            "box": {              "properties": {                "x": {                  "maximum": 1                },                "y": {                  "maximum": 1                },                "width": {                  "maximum": 1                },                "height": {                  "maximum": 1                }              }            },            "polygon": {              "items": {                "properties": {                  "x": {                    "maximum": 1                  },                  "y": {                    "maximum": 1                  }                }              }            },            "multi_polygon": {              "items": {                "items": {                  "properties": {                    "x": {                      "maximum": 1                    },                    "y": {                      "maximum": 1                    }                  }                }              }            }          }        }      }    }  }}

When unit is "per_mille", further limits apply.

Show the JSON Schema

{  "if": {    "properties": {      "unit": {        "const": "per_mille"      }    },    "required": [      "unit"    ]  },  "then": {    "properties": {      "objects": {        "items": {          "properties": {            "box": {              "properties": {                "x": {                  "maximum": 1000                },                "y": {                  "maximum": 1000                },                "width": {                  "maximum": 1000                },                "height": {                  "maximum": 1000                }              }            },            "polygon": {              "items": {                "properties": {                  "x": {                    "maximum": 1000                  },                  "y": {                    "maximum": 1000                  }                }              }            },            "multi_polygon": {              "items": {                "items": {                  "properties": {                    "x": {                      "maximum": 1000                    },                    "y": {                      "maximum": 1000                    }                  }                }              }            }          }        }      }    }  }}