Schema Validation Format

Video Metadata

Root Video Object

Field	Type	Description
version	Integer	Required. Must be set to 1.
overwrite	Boolean	Required. Must be set to true.
videos	Array <Video>	Required array of exactly one Video object.

Video Object

Field	Type	Description
id	String	Read-only. Unique identifier to reference this Video.It is included for reference when exporting metadata, but is ignored when importing metadata.
name	String	Optional string. Provide this field to update the Video name.
filename	String	Read-only. Indicates source Video filename.
description	String	Optional string. Provide this field to update a description of the Video.
location	String	Optional string. the location field is a string that describes the geographical location where the Video was taken, e.g. “Rocky Mountains, Colorado”, or “Downtown Los Angeles”.
tags	Array <String>	Optional array of zero or more non-empty strings. Allowed characters are lower case a-z, 0-9, hyphen, underscore, and space.
spectrum	String	Optional string. Provide this field to update Video color spectrum. Can be “RGB”, “Thermal”, “Mixed”, “Other”, “Unknown”.
assetType	String	Optional string. Provide this field to update Video asset type. Can be “RGB”, “Thermal”, “Mixed”, “Other”, “Unknown”.
frames	Array <Frame>	Optional array of zero or more Frame objects.
isRemoved	Boolean	Optional boolean. Set to true to set the Video as removed. “Removed” Videos will be retained in the database, but will not be displayed in Conservator.
owner	String	Optional lower case string. Provide an email address of an existing user to update the owner of the Video.
custom	Object	Optional blackbox object for storing custom Video metadata. Accepts any valid JSON object, including nested objects and arrays.

Frame Object

Field	Type	Description
frameIndex	Integer	Required. The zero-based frame index of the target Frame. Must be greater or equal to 0. The frameIndex must be unique and may not be greater than the highest frame index of the target Video.
id	String	Optional, read-only. Unique identifier used to reference this Frame. This frame is referenced when included in a Dataset, so the id should not be changed if provided.
videoId	String	Optional string. Unique identifier of source Video.
isEmpty	Boolean	Optional boolean. Set to “true” to mark this Frame as empty.
isFlagged	Boolean	Optional boolean. Set to “true” to flag frame.
spectrum	String	Optional string. Provide this field to update frame color spectrum. Can be “RGB”, “Thermal”, “Mixed”, “Other”, “Unknown”. Must match Video spectrum.
description	String	Optional string. Provide this field to update a description of the Frame. Must match Video description.
location	String	Optional string. The location field is a string that describes the geographical location where the image was taken, e.g. “Rocky Mountains, Colorado,”or “Downtown Los Angeles”. Must match source Video location.
tags	Array <String>	Optional array of zero or more non-empty strings. Allowed characters are lower case a-z, 0-9, hyphen, underscore, and space. Must match Video tags.
qaStatus	String	Optional string. Provide this field to update the Frame QA status. Can be “approved”, “changesRequested”, or null.
md5	String	Optional string. Represents payload of Frame image and is used for validation. Should not be modified
previewMd5	String	Optional string. Represents payload of Frame preview and is used for validation. Should not be modified
analyticsMd5	String	Optional string. Represents payload of Frame analytics and is used for validation. Should not be modified
annotations	Array <Annotation>	Optional array of zero or more Annotation objects. Providing an array of Annotation objects replaces all Annotations in the current Frame with the provided Annotations. To remove all Annotations for the current Frame, provide an empty array. Omit this field completely to leave the existing Annotations for the current Frame intact.
attributes	Array <Attribute>	Optional array of attributes.
associatedFrames	Array <Associated Frame>	Optional array of associated frames linked to this Frame.
custom	Object	Optional blackbox object for storing custom Frame metadata. Accepts any valid JSON object, including nested objects and arrays.

Dataset Object

Field	Type	Description
datasetId	String	Read-only. Unique identifier used to reference this dataset.
datasetName	String	Required string. Edit this field to update the Dataset name.
overwrite	Boolean	Required. Must be set to true.
version	Integer	Required. Must be set to 1.
owner	String	Optional lower case string. Provide an email address of an existing user to update the owner of the Dataset.
videos	Array <Video>	Array of zero or more reduced Video objects that are included in the Dataset.
frames	Array <DatasetFrame>	Optional array of zero or more DatasetFrame objects.
description	String	Optional string. Provide this field to update the Dataset description.
custom	Object	Optional blackbox object for storing custom Dataset metadata. Accepts any valid JSON object, including nested objects and arrays.

DatasetFrame Object

Field	Type	Description
datasetFrameId	String	Required, read-only. Unique identifier used to reference this DatasetFrame. Should not be changed.
isEmpty	Boolean	Optional boolean. Set to “true” to mark this DatasetFrame as empty.
isFlagged	Boolean	Optional boolean. Set to “true” to flag this DatasetFrame.
qaStatus	String	Optional string. Provide this field to update the DatasetFrame QA status. Can be “approved”, “changesRequested”, or null.
qaStatusNote	String	Optional string. Provide this field to include a note on this DatasetFrame’s QA status.
md5	String	Optional string. Represents payload of this DatasetFrame and is used for validation and is used for validation. Should not be modified.
previewMd5	String	Optional string. Represents payload of frame preview and is used for validation. Should not be modified
analyticsMd5	String	Optional string. Represents payload of analytics and is used for validation. Should not be modified
attributes	Array <Attribute>	Optional array of attributes.
tags	Array <String>	Optional array of zero or more non-empty strings. Allowed characters are lower case a-z, 0-9, hyphen, underscore, and space.
videoMetadata	Video Metadata	Optional Video Metadata Object containing metadata of DatasetFrame as referenced in the source Video.
height	Integer	Read-only. Pixel height of DatasetFrame.
width	Integer	Read-only. Pixel width of DatasetFrame.
fileSize	Integer	Read-only. File size of DatasetFrame.
annotations	Array <Annotation>	Optional array of zero or more Annotation objects. Providing an array of Annotation objects replaces all Annotations in the current DatasetFrame with the provided Annotations. To remove all Annotations for the current DatasetFrame, provide an empty array. Omit this field completely to leave the existing Annotations for the current DatasetFrame intact.
datasetFrameId	String	Required, read-only string. Unique identifier used to reference this DatasetFrame.
spectrum	String	Optional string. Provide this field to update DatasetFrame color spectrum. Can be “RGB”, “Thermal”, “Mixed”, “Other”, “Unknown”.
description	String	Optional string. Provide this field to update the DatasetFrame description.
location	String	Optional string. The location field is a string that describes the geographical location where the image was taken, e.g. “Rocky Mountains, Colorado,” or “Downtown Los Angeles”.
custom	Object	Optional blackbox object for storing custom DatasetFrame metadata. Accepts any valid JSON object, including nested objects and arrays.
associatedFrames	Array <Associated Frame>	Optional array of associated Frames linked to this DatasetFrame.

Associated Frame Object

Field	Type	Description
spectrum	String	Required string. Provide this field to update Video color spectrum. Can be “RGB”, “Thermal”, “Mixed”, “Other”, “Unknown”.
frameId	String	Required string if datasetFrameId is not provided. Unique identifier pointing to associated Frame.
datasetFrameId	String	Required string if frameId is not provided. Unique identifier pointing to associated DatasetFrame.

Video Metadata

Field	Type	Description
frameId	String	Required string. Unique identifier pointing to Frame as referenced in the source Video.
frameIndex	Integer	Required integer. Index of Frame as referenced in the source Video.
videoId	String	Optional string. Unique identifier of source Video.

Annotation Metadata

Annotation Object

Field	Type	Description
labels	Array <String>	Required array of exactly one string. Must match the label referenced by labelId. Allowed characters are lowercase a-z, 0-9, hyphen, underscore, and space.
targetId	String	Optional, non-empty string. The targetId is the identity of the annotated target object (eg. a person, dog, car, etc.), to support applications that track the target over time. Subsequent Frames of the same object in a Video would have the same targetId.
labelId	String	Optional string. Unique identifier used to point to a specific label.
source	source	Contains the meta for this Annotation.
boundingBox	BoundingBox	Optional BoundingBox object. The BoundingBox describes the position and size of the Annotation.
boudingPolygon	Array <Point>	Optional ordered array of Points enclosing an area describing the shape and position of the Annotation.
point	Point	Single Point describing the position of the Annotation.
attributes	Array <Attribute>	Optional array of attributes.
custom	Object	Optional blackbox object for storing custom annotation metadata. Accepts any valid JSON object, including nested objects and arrays.
qaStatus	String	Optional string. Provide this field to update the annotation QA status. Can be “approved”, “changesRequested”, or null.
qaStatusNote	String	Optional string. Provide this field to update the frame QA status. Can be “approved”, “changesRequested”, or null.

Bounding Box Object

Field	Type	Description
x	Integer	Required. The X position of the top-left corner of the bounding box.
y	Integer	Required. The Y position of the top-left corner of the bounding box.
w	Integer	Required. The pixel width of the bounding box. Must be greater or equal to 1.
h	Integer	Required. The pixel height of the bounding box. Must be greater or equal to 1.

Point Object

Field	Type	Description
x	Integer	Required. The X position of the point.
y	Integer	Required. The Y position of the point.

Annotation Source

Field	Type	Description
meta	Annotation Meta	Annotation meta object. Contains annotation metadata tracked by Conservator.
type	String	Optional string. Describes whether an annotation was created by a person or ML algorithm. Can be “human,” “machine,” or “unknown.”

Annotation Meta

Field	Type	Description
tool	String	Optional string. The name of the tool used to create the annotation. Can be any string.
user	String	Optional string. Id of user who created this annotation.

Other

Attribute Object

Field	Type	Description
name	String	Required string. Update to change the name of the attribute.
value	String	Required string. The value of the attribute; e.g. if an attribute is for “time of day”, the value could be “morning”.
_id	String	Read-only. Unique identifier used to point to this attribute.
options	Array<String>	Optional string. Provides a list of options for attributes of type radio, checklist, or dropdown.
source	String	Optional string. If does provided, it will be defaulted to “Unknown”.
type	String	Optional string. Indicates the type of attribute. Can be “dropdown”, “radio”, “checklist”, “text”, or “number”.
attributePrototypeId	String	Optional string. Indicates the identifier of the attribute’s prototype, which describes the type and options for the attribute.

Video Example

{
  "version": 1,
  "overwrite": true,
  "videos": [
    {
      "id": "Fo0xyh8b8UpQvggkt",
      "name": "My first video",
      "description": "Example video",
      "location": "Lisbon, Portugal",
      "tags": ["traffic", "rushhour"],
      "owner": "user@example.com",
      "frames": [
        {
          "frameId": "dEWCFckMWbFQ6ZEDY",
          "frameIndex": 0,
          "md5": "2b5716cba5c13a0dee89a81445a16a23",
          "annotations": [
            {
              "targetId": 1,
              "labels": ["car"],
              "labelId": "kq6JufsKuHzbnDGin",
              "source": {
                "type": "human",
                "meta": {
                "user": "AMzBYPRsQkpRc4Quq",
                "tool": "conservator"
              }
              "boundingBox": {"x": 100, "y": 100, "w": 100, "h": 100}
            },
            {
              "targetId": 2,
              "labels": ["deer"],
              "boundingBox": {"x": 200, "y": 200, "w": 200, "h": 200}
            }
          ]
        },
        {
          "frameIndex": 1,
          "annotations": [
            {
              "targetId": 1,
              "labels": ["car"],
              "boundingBox": {"x": 100, "y": 100, "w": 100, "h": 100}
            },
            {
              "targetId": 2,
              "labels": ["deer"],
              "boundingBox": {"x": 200, "y": 200, "w": 200, "h": 200}
            }
          ]
        }
      ]
    }
  ]
}

Dataset Example

{
 "datasetId": "ZlPS8p9dj9y4Gexqp",
 "datasetName": "My first dataset",
 "description": "Example dataset",
 "frames": [
  {
   "annotations": [
    {
     "boundingBox": {
      "h": 260,
      "w": 327,
      "x": 448,
      "y": 434
     },
     "id": "eiDuF6vxeoqSR485X",
     "labelId": "kq6JufsKuHzbnDGin",
     "labels": [
      "bicycle"
     ],
     "source": {
      "meta": {
       "tool": "conservator",
       "user": "AMzBYPRsQkpRc4Quq"
      },
      "type": "human"
     }
    },
    {
     "boundingPolygon": [
      {
       "x": 114,
       "y": 115
      },
      {
       "x": 178,
       "y": 164
      },
      {
       "x": 128,
       "y": 203
      },
      {
       "x": 62,
       "y": 158
      }
     ],
     "id": "46mufjw9utSp6zK6E",
     "labelId": "JMFeHCG8afceDnfzg",
     "labels": ["star"],
     "source": {
      "meta": {
       "tool": "conservator",
       "user": "AMzBYPRsQkpRc4Quq"
      },
      "type": "human"
     }
    },
   ],
   "datasetFrameId": "ZoerBFrTm6rqd9L2a",
   "fileSize": 75242,
   "height": 540,
   "isEmpty": false,
   "isFlagged": false,
   "md5": "f48b9db8ce01e29dbe369839b7798b51",
   "previewMd5": "103faa27e04cf8f28ae3af6991e300cd",
   "spectrum": "Unknown",
   "videoMetadata": {
    "frameId": "acnbbFvZQFTkrSiKp",
    "frameIndex": 0,
    "videoId": "Fo0xyh8b8UpQvggkt"
   },
   "width": 720
  },
 ],
 "overwrite": true,
 "owner": "user@example.com",
 "version": 1,
 "videos": [
  {
   "filename": "my_first_video.zip",
   "id": "Fo0xyh8b8UpQvggkt",
   "name": "My first video",
   "owner": "user@example.com",
   "spectrum": "Unknown"
  }
 ]
}