Tags

In Supervisely tags provide an option to associate some additional information with the labeled image or the labels on it. Each individual tag can be attached to a single image or asingle annotation only once, but there's not limit on how many times the same tag can be attached to different parts of the scene. There are different lists of tags for images and figures in the annotation file.

When defining a tag, you assign it a name, possible values for a tag instance and what types of things it can be attached to. We support values of the following types: None (without an assigned value), Text, Number, One of, and Date.

Tags With 'None' Value

Tags of 'none' type can't be assigned a value. Adding one manually will result in an error. Also it could not be used as a group tag for the multiview mode.

Json format for 'None' tags:

{
    "id": 86334622,
    "tagId": 28256197,
    "labelerLogin": "alexxx",
    "createdAt": "2020-08-23T09:51:06.246Z",
    "updatedAt": "2020-08-23T09:51:06.246Z",
    "name": "like",
    "value": null
}

Fields definitions:

• name - string - name of the tag

• value - value of the current tag (always null for any tag of type 'none')

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt will be described below

Tag with 'Number' Value

Tags of type 'number' can only take a numeric value. Adding a different type of value during manual annotation will result in an error.

Json format for 'Number' tags:

{
    "id": 98753625,
    "tagId": 28256196,
    "labelerLogin": "alexxx",
    "createdAt": "2020-08-26T08:23:24.644Z",
    "updatedAt": "2020-08-26T08:23:24.644Z",
    "name": "cars_number",
    "value": 700
}

Fields definitions:

• name - string - name of the tag

• value - value of the current tag

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt will be described below

Tag with String('Text') Value

Tags of type 'string' can only take a string value. Adding a different type of value during manual annotation will result in an error.

Json format for 'text' tags:

{
    "id": 95462538,
    "tagId": 28256201,
    "labelerLogin": "alexxx",
    "createdAt": "2020-07-24T07:30:39.202Z",
    "updatedAt": "2020-07-24T07:30:39.202Z",
    "name": "car_color",
    "value": "red"
}

Fields definitions:

• name - string - name of the tag

• value - value of current tag

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt will be described below

Tag with value from a given list ('One Of')

Tag of type 'One Of' can only take a value from the list of possible values for this tag. List of possible values is set when creating the tag. Adding a value not from the list during manual annotation will result in an error.

Json format for 'one of' tags:

 {
    "id": 86334621,
    "tagId": 28256198,
    "labelerLogin": "alexxx",
    "createdAt": "2020-08-23T09:51:02.843Z",
    "updatedAt": "2020-08-23T09:51:02.843Z",
    "name": "situated",
    "value": "outside"
}

Fields definitions:

• name - string - name of the tag

• value - value of current tag

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt will be described below

Tag with 'Date' Value

Tags of type 'date' store an ISO 8601 datetime string. Use this tag type to record dates and times for images or objects in the Labeling Tool via the date picker—for widget.

This tag type can be useful for various purposes, such as tracking the date and time of image review, recording when a specific event occurred, or any other scenario where associating a timestamp with an image or annotation is beneficial.

Json format for 'date' tags:

{
    "id": 102837465,
    "tagId": 28256210,
    "labelerLogin": "alexxx",
    "createdAt": "2026-04-23T15:15:48.000Z",
    "updatedAt": "2026-04-23T15:15:48.000Z",
    "name": "reviewed_at",
    "value": "2026-04-23T15:15:48"
}

Fields definitions:

• name - string - name of the tag

• value - ISO 8601 datetime string. Accepted formats:

  • 2026-04-23T15:15:48 (basic ISO format)

  • 2026-05-12T21:14:12.000Z (UTC with milliseconds)

  • 2026-04-27 11:00:46 (space separator instead of T)

  • 2026-05-12T21:14:12+00:00 (explicit timezone offset)

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt will be described below

Optional fields

The following fields are created and assigned automatically by the system when the tags are first created in it (or the data is uploaded). This means these fields are optional and you don't have to assign them during manual annotation.

Optional fields:

"id": 503051990,
"tagId": 1693352,
"labelerLogin": "alexxx",
"createdAt": "2020-08-22T09:32:48.010Z",
"updatedAt": "2020-08-22T09:33:08.926Z".

Fields definitions:

• id - unique identifier of the current object

• tagId - unique tag identifier of the current object

• labelerLogin - string - the name of user who created the current figure

• createdAt - string - date and time of figure creation

• updatedAt - string - date and time of the last figure update

Custom data

A tag assignment can carry arbitrary user JSON in the optional customData field. It is independent of the tag definition and of the tag value, so the same tag can carry different custom data on every entity it is attached to.

{
    "id": 503051990,
    "tagId": 1693352,
    "name": "cat",
    "value": "fluffy",
    "customData": {
        "confidence": 0.92,
        "source": "model_v3",
        "reviewed": false,
        "bbox_hint": [10, 20, 30, 40],
        "meta": { "title": "kept as-is", "groupId": 7 }
    }
}

Fields definitions:

• customData - object - arbitrary JSON. Nested objects and arrays are allowed, and keys are never renamed or stripped, so reserved-looking names such as title or groupId come back exactly as they were stored.

The key is present only when it is not empty, so annotations of projects that never use the feature are unchanged. Image, object (figure) and annotation object tags all support it.

In the Python SDK it is the custom_data property of Tag, VideoTag, VolumeTag and PointcloudTag, and it is preserved through annotation download and upload:

tag = sly.Tag(
    meta=project_meta.get_tag_meta("cat"),
    value="fluffy",
    custom_data={"confidence": 0.92, "source": "model_v3"},
)

Examples

Image tags:

Json format for image tags:

"tags": [
    {
        "id": 86334622,
        "tagId": 28256197,
        "labelerLogin": "alexxx",
        "createdAt": "2020-08-23T09:51:06.246Z",
        "updatedAt": "2020-08-23T09:51:06.246Z",
        "name": "like",
        "value": null
    },
    {
        "id": 86334621,
        "tagId": 28256198,
        "labelerLogin": "alexxx",
        "createdAt": "2020-08-23T09:51:02.843Z",
        "updatedAt": "2020-08-23T09:51:02.843Z",
        "name": "situated",
        "value": "outside"
    }
]

Fields definitions:

• name - string - name of the tag

• value - value of current tag

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt are described above

Objects tags:

Json format for object tags:

"tags": [
    {
        "id": 95462539,
        "tagId": 28256199,
        "labelerLogin": "alexxx",
        "createdAt": "2020-07-24T07:30:39.202Z",
        "updatedAt": "2020-07-24T07:30:39.202Z",
        "name": "vehicle_age",
        "value": "vintage"
    },
    {
        "id": 95462538,
        "tagId": 28256201,
        "labelerLogin": "alexxx",
        "createdAt": "2020-07-24T07:30:39.202Z",
        "updatedAt": "2020-07-24T07:30:39.202Z",
        "name": "car_color",
        "value": "red"
    }
]

Fields definitions:

• name - string - name of the tag

• value - value of current tag

• Optional fields id, tagId, labelerLogin, createdAt, updatedAt are described above