> ## Documentation Index
> Fetch the complete documentation index at: https://api-reference.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Labels

> Label Nesting and Options Response Format

# Label Nesting and Options

There are often annotation tasks that have too many label choices for a tasker to efficiently sort through them all at once, or times when you want to show one version of a label name to a tasker, but would like another version in the response.

In those cases, you can utilize `LabelDescription` objects to support nested labels, where labels may have subcategories within them, as well as setting `display` values for the label.

When declaring `objects_to_annotate` in your task parameters, we accept a mixed array of strings and the more complex `LabelDescription` objects.

### Definition: `LabelDescription`

The `LabelDescription` object has the following structure:

<ParamField path="Parameters" type="object">
  <ParamField path="choice" type="string" required>
    The name of the label. This should be singular and descriptive (ex: `car`, `background`, `pole`).<br /><br />When both a `choice` and `subchoices` are defined, the `choice` will not be selectable, it will only be used for UX navigation. Only the "leaf" nodes will be returned in Scale's response.

    ***
  </ParamField>

  <ParamField path="subchoices" type="array of objects">
    Optional: Descriptions of the sub-labels to be shown under this parent label. Array can be a mix of LabelDescription objects or strings.

    ***
  </ParamField>

  <ParamField path="instance_label" type="boolean">
    Optional: For Segmentation-based Tasks - Whether this label should be segmented on a per-instance basis. For example, if you set `instance_label` to `true`, each individual car would get a separate mask in the image, allowing you to distinguish between them.

    ***
  </ParamField>

  <ParamField path="display" type="string">
    Optional: The value to be shown to a Tasker for a given label. Visually overrides the `choice` field in the user experience, but does not affect the task response or conditionality.

    ***
  </ParamField>
</ParamField>

A simple example is illustrated in the example JSON below, where `objects_to_annotate` can simply be a string, a nested label with choices and subchoices, or a nested label where the subchoices themselves are `LabelDescription` objects with a display value.

While there may be a large number of total labels, using subchoices a tasker can first categorize an object as a road, pedestrian, or vehicle, and based on that choice, further select the specific type of pedestrian or vehicle.

Nested labels may be specified both for the object labels (the `objects_to_annotate` array parameter), as well as in the `choices` array of a categorical annotation attribute. In both cases, you would specify a nested label by using a `LabelDescription` object instead of a string.

For example, for an `objects_to_annotate` array of `\["Vehicle", "Pedestrian"\]`, you could instead add a nested label by passing an array, like `\["Vehicle", \{"choice": "Pedestrian", "subchoices": \["Animal", "Adult", "Child"\]\}\]`. Then, if a tasker selected "Pedestrian" for an annotation, they would be further prompted to choose one of the corresponding subchoices for that annotation.

> 📘 See the [Conditional attributes section](/docs/api-reference/annotation-attributes#conditionality) for more details about conditional attributes.

```json theme={null}
objects_to_annotate = [
  "Road",
  {
    "choice": "Vehicle",
    "subchoices": ["Car", "Truck", "Train", "Motorcycle"]
  },
  {
    "choice": "Pedestrian",
    "subchoices": [
      "Animal", 
      {"choice": "Ped_HeightOverMeter", "display": "Adult" }, 
      {"choice": "Ped_HeightUnderMeter", "display": "Child" }, 
    ]
  }
]
```

# Response Format

Nested labels are only intended for grouping a large set of labels together. Thus, the response will be the same as with unnested labels, where only the final "leaf" label that the worker selected is reported. In the example above, if a worker selected "Pedestrian" and then "Animal" for an annotation, that annotation's label would be "Animal".

```json theme={null}
{
  "task_id": "5774cc78b01249ab09f089dd",
  "created_at": "2016-9-03T07:38:32.368Z",
  "callback_url": "http://www.example.com/callback",
  "type": "annotation",
  "status": "pending",
  "instruction": "Annotate the cars and pedestrians",
  "params": {
    "attachment": "https://i.imgur.com/VDPoOZE.jpg",
    "attachment_type": "image",
    "objects_to_annotate": [
      {
        "choice": "Vehicle",
        "subchoices": ["Car", "Truck", "Train", "Motorcycle"]
      },
      {
        "choice": "Pedestrian",
        "subchoices": ["Animal", "Adult", "Child"]
      }
    ],
    "with_labels": false,
    "min_width": 30,
    "min_height": 30,
    "examples": [],
    "annotation_attributes": {
      "occlusion": {
        "description": "What percent of the object is occluded?",
        "choices": ["0%", "25%", "50%", "75%"],
        "conditions": {
          "label_condition": {
            "label": ["Car", "Truck", "Motorcycle"]
          }
        }
      }
    }
  },
  "metadata": {}
}
```

```json theme={null}
{
  "response": {
    "annotations": [
      {
        "left": 123,
        "top": 10,
        "width": 121,
        "height": 39,
        "label": "Motorcycle",
        "attributes": {
          "occlusion": "0%"
        }
      },
      {
        "left": 82,
        "top": 56,
        "width": 64,
        "height": 30,
        "label": "Animal"
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}
```