Darwin JSON is one of the annotation formats supported by V7. It's the default annotation encoding within the platform.

When a Dataset or a subset of images and videos is exported from Darwin, an archive is generated. The archive includes a set of JSON files encoded in the Darwin JSON format. Each file references images or videos within each slot of an item, and contains the entirety of the annotations that have been made and approved for that item.

The format is also at the core of the Darwin Python Library for both Dataset management and Deep Learning.

This document aims to document the Darwin JSON format in its entirety.
At the end of the document, a set examples will be shown and documented for both exported images and videos.

🚧
Darwin JSON V2.0
This page refers to Darwin JSON v2.0 which is available on v2.0 datasets only. Please refer to our Darwin JSON v1.0 documentation for more details on the legacy format.

Fields

Export

The content of each Darwin JSON file can be summarised by the following specifications.

type Export = {
  version: string,
  annotations: ImageAnnotation[] | VideoAnntoation[],
  dataset: string,
  item: slots[],
  slots: image[] | video[]
}

An Export includes all the information about the exported resource. The item field includes information about the referenced resource, that is the image or video uploaded to Darwin within particular slots; the dataset field simply encodes the Darwin Dataset name that resource belongs to; the annotations field lists all the annotations created on Darwin for that resource. The version field will be "2.0" when the export format is Darwin JSON 2.0.

Let's see what the item, slots,Image, Video, ImageAnnotation and VideoAnnotation fields look like.

The item field

The 'item' field contains metadata for the given exported item and the files within its slots.

type item = {
  /** Internal filename of the item on V7 */
  name: string,
  /** The path of the file within Darwin.
    * The path starts at root ("/"), and expands including the
    * folders in which the resource is stored.
    */
  path: string,
  /** Object containing V7 source information for the item */
  source_info: source_info,
  /** List of slots metadata */
  slots: slots[],  
  /** The URL of the image on Darwin.
    * It routes directly to the Darwin Workview
    */
  workview_url: string
}


type source_info = {
  /** Dataset object containgin information for this item in V7 */
  dataset: dataset,
  /** Unique ID for this item in V7 */
  item_id: string,
  /** Team object containing information for this item in V7 */
  team: team,
  /** The URL of the image on Darwin.
    * It routes directly to the Darwin Workview
    */
  workview_url: string
}


type dataset = {
  /** Name of the dataset containing this item in V7 */
  name: string,
  /** Sluggified name of the dataset containing this item in V7 */
  slug: string,
  /** URL to the dataset management page for this dataset */
  dataset_management_url: string,
}

type team = {
  /** Name of the team containing this item in V7 */
  name: string,
  /** Sluggified name of the team containing this item in V7 */
  slug: string,
}

The slots field

The slots field has a list where an object of an Export is either of type Image or video.

Image

An Image describes an image resource uploaded to Darwin, including its original metadata.

type Image = {
  /** Internal filename of a particular slot on Darwin */
  slot_name: string,
  /** Height of the image */
  height: integer,
  /** Source file metadata */
  source_files: source_files[],
  /** The URL of the image thumbnail */
  thumbnail_url: string,
  /** Width of the image */
  width: integer,
}

type source_files {
  /** The name of the original image */
  file_name: string,
  /** The URL of the original image */
  url: string,
}

Video

A Video describes a video resource uploaded to Darwin, including its original metadata.

type Video = {
  /** Internal filename on Darwin */
  slot_name: string,
  /** Frame-rate in which the video has been annotated on Darwin */
  fps: number,
  /** The number of frames generated from the original video */
  frame_count: integer,
  /** The URLs of the frames generated from the original video */
  frame_urls: string[],
  /** The path of the file within Darwin.
    * The path starts at root ("/"), and expands including the
    * folders in which the resource is stored.
    */
  /** Height of the video frame */
  height: integer,
  path: string,
  /** Source file metadata */
  source_files: source_files[],
  /** Width of the video frame */
  width: integer,
}

type source_files {
  /** The name of the original image */
  file_name: string,
  /** The URL of the original image */
  url: string,
}

The annotations field

The annotations field lists all the annotations created on Darwin for an image or video, and its encoded respectively as an ImageAnnotation or VideoAnnotation. Let's see what they look like.

ImageAnnotation

An ImageAnnotation encodes the information of an annotation created on a image on Darwin. It includes the annotation data itself, but also the annotation class name and it may optionally include authorship information.

type ImageAnnotation = {
  /** An optional list of annotators of the image */
  annotators: Authorship[] | undefined,
  /** The annotation class name */
  name: string,
  /** An optional list of reviewers of the image */
  reviewers: Authorship[] | undefined,
  /** A list of the different slot names */
  slot_names: string[],
  /** A list of linked properties */
  properties: Property[],
  /** The actual data of the annotation */
  [annotation_type: MainAnnotationType]: AnnotationData,
  /** Optional sub annotation data **/
  ...[annotation_type: SubAnnotationType]: AnnotationData
}

To have a full overview and give an example of an ImageAnnotation, let's define the Authorship, MainAnnotationType, SubAnnotationType, SlotNames and AnnotationData

Authorship

An Authorship object encodes the information of a Darwin annotator or reviewer. It only includes their email and full name.

type Authorship = {
  /** Email of the annotator or reviewer on Darwin */
  email: string,
  /** Full name (first name + last name) of the annotator or reviewer */
  full_name: string
}

Property

A propertyobject encodes the information of linked property value. It is also present when a property is not linked but is required for the annotation class. In this case, the value field is null.

type Property = {
  /** Frame index of the property. For image annotations is always set to 0. */
  frame_index: integer,
  /** Name of the property */
  name: string,
  /** Linked value */
  value: string
}

MainAnnotationType

A MainAnnotationType type simply encodes a string of one of the main annotation types available on Darwin. Note that a single annotation includes one and only one main annotation type.

type MainAnnotationType =
  'bounding_box' |
  'ellipse' |
  'line' |
  'keypoint' |
  'polygon' |
  'skeleton' |
  'tag' |
  'mask' |
  'raster_layer'

📘
Complex Polygons
Complex polygons are now included as a part of the polygon annotation type and the complex_polygon annotation type has been deprecated in V2.

SubAnnotationType

A SubAnnotationType type encodes a simple string of one of the sub annotation types supported on Darwin. Note that a single annotation may include multiple sub annotation types, provided that the main annotation type supports them.

type SubAnnotationType =
  'attributes' |
  'directional_vector' |
  'instance_id' |
  'text'

SlotNamesType

The SlotNamesType type is a list of strings denoting the slot(s) of the MainAnnotationType

type SlotNamesType = {
  /** List of slot names */
  slot_names: string[]
}

🚧
V2.0 Feature
Slots are only supported in V2.0 and are currently not supported by export formats other than Darwin JSON.

AnnotationData

AnnotationData represents the core data of an annotation created on Darwin.

type AnnotationData =
  Attributes |
  BoundingBox |
  DirectionalVector |
  Ellipse |
  InstanceID |
  Line |
  Keypoint |
  Polygon |
  Skeleton |
  Tag |
  Text |
  Mask |
  RasterLayer

type Attributes = {
  /** List of attribute names */
  attributes: string[]
}

type BoundingBox = {
  /** Height of the bounding box */
  h: float,
  /** Width of the bounding box */
  w: float,
  /** Left-most coordinate of the bounding box */
  x: float,
  /** Top-most coordinate of the bounding box */
  y: float
}

type DirectionalVector = {
  /** Orientation of the vector in radians */
  angle: float,
  /** Length of the vector */
  length: float
}

type Ellipse = {
  /** Orientation of the ellipse in radians */
  angle: float,
  /** The center point of the ellipse */
  center: Keypoint,
  /** The two radii of the ellipse, encoded as a point */
  radius: Keypoint
}

type InstanceID = {
  /** The positive integer value assigned to the annotation */
  value: number
}

type Line = {
  /** A list of adjacent points, to be considered as an open path */
  path: Keypoint[]
}

type Keypoint = {
  /** The horizontal coordinate of the keypoint */
  x: number,
  /** The vertical coordinate of the keypoint */
  y: number
}

type Polygon = {
  /** A list of lists of adjacent points with each list being a closed path */
  paths: Keypoint[][]
}

type Skeleton = {
  /** A list of skeleton nodes */
  nodes: {
    /** The name of the node */
    name: string,
    /** A boolean value, which is true when the node is occluded,
      * or false when the node is visible
      */
    occluded: boolean,
    /** The horizontal coordinate of the keypoint */
    x: number,
    /** The vertical coordinate of the keypoint */
    y: number
  }[]
}

type Tag = {}

type Text = {
  /** The actual text */
  text: string
}

type Mask = {}

type RasterLayer = {
  /** The mapping of mask annotation identifiers 
    * to unique positive integer references used in dense_rle
    */
  mask_annotation_ids_mapping: Record<string, number>,
  /** The total number of pixels which is equal to
    * a product of width ad height of an image or frame
    */
  total_pixels: number,
  /** The variation of RLE where free space is included in encoding. 
    * It represents all masks as a flat array.
    * The array always contains an even number of elements because they are paired.
    * The first value in a pair is a positive integer which is a mask annotation reference
    * or 0 representing free space from annotations.
    * The second element is the number of pixels included in the current consequent segment.
    * The sum of all segment lengths must be equal to the value of the total_pixels field.
    */
  dense_rle: number[]
}

VideoAnnotation

A VideoAnnotation object encodes the information of an annotation created on a video on Darwin. It includes all the frame annotation data, but also the annotation class name, interpolation information, and it may optionally include authorship information.

type VideoAnnotation = {
  annotators: Authorship[] | undefined,
  frames: Frame[],
  interpolate_algorithm: string,
  interpolated: boolean,
  name: string,
  slot_names: string[],
  reviewers: Authorship[],
  ranges: Ranges[],
  properties: Property[]
}

🚧
Ranges
'Ranges' field (previously called 'Segments' in Darwin JSON V1 format) denotes the frame range of a given annotation instance . Note that frames are zero-indexed, and 'Ranges' behaves the same way as the range() python function. This means that:

The first value is the index of the first frame the annotation is present in

The second value is the index of the frame after the last frame the annotation is present in

All other fields in this section are unchanged.

The core data of a VideoAnnotation can be found in the frames field. Each Frame can be described as an AnnotationData, but with additional data depending on the way the frame was created on Darwin (e.g. manually by an annotator, or programmatically by the interpolation algorithm).

Frames

A Frame object encodes the information of a frame annotation, either manually created by the annotators on Darwin, or algorithmically interpolated by the specified VideoAnnotation's interpolated_algorithm field.

type Frame: {
  [frame_key: string]: {
    keyframe: boolean,
    [annotation_type: MainAnnotationType]: AnnotationData,
    ...[annotation_type: SubAnnotationType]: AnnotationData
  }
}

Darwin JSON 2.0 Schema

Below is the full schema for Darwin JSON 2.0

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Darwin JSON Format for Image and Sequence annotations",
  "type": "object",
  "properties": {
    "version": {
      "description": "The version of this Darwin JSON document.",
      "type": "string",
      "enum": [
        "2.0"
      ]
    },
    "schema_ref": {
      "description": "URL to JSON schema describing this document.",
      "type": "string"
    },
    "item": {
      "description": "Metadata describing context of annotations",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the Item",
          "type": "string"
        },
        "path": {
          "description": "Path of the Item",
          "type": "string"
        },
        "source_info": {
          "description": "Additional information about the Item's source",
          "type": "object",
          "properties": {
            "dataset": {
              "description": "Dataset information",
              "type": "object",
              "properties": {
                "name": {
                  "description": "Name of the Dataset",
                  "type": "string"
                },
                "slug": {
                  "description": "Slug of the Dataset",
                  "type": "string"
                },
                "dataset_management_url": {
                  "description": "URL for dataset management UI for this Dataset",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "slug"
              ]
            },
            "item_id": {
              "description": "UUID of this Item on Darwin platform",
              "type": "string"
            },
            "workview_url": {
              "description": "URL to workview UI for this Item",
              "type": "string"
            },
            "team": {
              "description": "Team information",
              "type": "object",
              "properties": {
                "name": {
                  "description": "Name of the Team",
                  "type": "string"
                },
                "slug": {
                  "description": "Slug of the Team",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "slug"
              ]
            }
          },
          "required": [
            "item_id"
          ]
        },
        "slots": {
          "description": "Additional information about all slots that are part of this Item",
          "type": "array",
          "items": {
            "description": "Information about Item's slot",
            "type": "object",
            "properties": {
              "type": {
                "description": "Type of the slot",
                "type": "string"
              },
              "slot_name": {
                "description": "Slot's name",
                "type": "string"
              },
              "width": {
                "description": "Slot's width in pixels",
                "type": "number"
              },
              "height": {
                "description": "Slot's height in pixels",
                "type": "number"
              },
              "thumbnail_url": {
                "description": "URL to the thumbnail image of this Slot",
                "type": "string"
              },
              "source_files": {
                "description": "List of originally uploaded files that created this Slot",
                "type": "array",
                "items": {
                  "description": "Uploaded file that is part of this Slot",
                  "type": "object",
                  "properties": {
                    "file_name": {
                      "description": "Name of the original file",
                      "type": "string"
                    },
                    "url": {
                      "description": "URL to download the original file",
                      "type": "string"
                    },
                    "local_path": {
                      "description": "Local path of where the file was downloaded with DarwinPy.",
                      "type": "string"
                    },
                    "storage_key": {
                      "description": "Path to the file on source storage (only available for external storage files).",
                      "type": "string"
                    },
                    "storage_slug": {
                      "description": "Name-slug of the source storage (only available for external storage files).",
                      "type": "string"
                    }
                  },
                  "required": [
                    "file_name",
                    "url"
                  ]
                }
              }
            },
            "required": [
              "type",
              "slot_name",
              "source_files"
            ]
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "name",
        "path"
      ]
    },
    "annotations": {
      "type": "array",
      "items": {
        "if": {
          "properties": {
            "frames": {

            }
          },
          "required": [
            "frames"
          ]
        },
        "then": {
          "$ref": "#/$defs/sequenceAnnotation"
        },
        "else": {
          "$ref": "#/$defs/imageAnnotation"
        }
      }
    },
    "workflow": {
      "description": "Metadata describing the workflow item connected to. Included only in the webhook payload.",
      "type": "object",
      "properties": {
        "id": {
          "description": "UUID of the workflow",
          "type": "string"
        },
        "current_stage_id": {
          "description": "UUID of the current stage",
          "type": "string"
        },
        "events": {
          "description": "List containing latest stage transition event",
          "type": "array",
          "items": {
            "$ref": "#/$defs/workflowEvent"
          }
        }
      },
      "required": [
        "id",
        "current_stage_id",
        "events"
      ]
    }
  },
  "required": [
    "version",
    "item",
    "annotations"
  ],
  "additionalProperties": false,
  "$defs": {
    "boundingBox": {
      "description": "A Bounding Box's details",
      "type": "object",
      "properties": {
        "x": {
          "description": "X coordinate of the top-left corner of the bounding box",
          "type": "number"
        },
        "y": {
          "description": "Y coordinate of the top-left corner of the bounding box",
          "type": "number"
        },
        "w": {
          "description": "Width of the bounding box",
          "type": "number"
        },
        "h": {
          "description": "Height of the bounding box",
          "type": "number"
        }
      },
      "required": [
        "x",
        "y",
        "w",
        "h"
      ],
      "additionalProperties": false
    },
    "boundingBoxAnnotation": {
      "description": "A Bounding Box annotation",
      "type": "object",
      "properties": {
        "bounding_box": {
          "$ref": "#/$defs/boundingBox"
        }
      },
      "required": [
        "bounding_box"
      ]
    },
    "polygonAnnotation": {
      "description": "A Polygon annotation",
      "type": "object",
      "properties": {
        "bounding_box": {
          "$ref": "#/$defs/boundingBox"
        },
        "polygon": {
          "description": "A Polygon annotation",
          "type": "object",
          "properties": {
            "paths": {
              "description": "A list of paths that define a polygon",
              "type": "array",
              "items": {
                "description": "A list of points defining a single path of the polygon",
                "type": "array",
                "items": {
                  "description": "A point",
                  "type": "object",
                  "properties": {
                    "x": {
                      "description": "X coordinate of the point",
                      "type": "number"
                    },
                    "y": {
                      "description": "Y coordinate of the point",
                      "type": "number"
                    }
                  },
                  "required": [
                    "x",
                    "y"
                  ],
                  "additionalProperties": false
                },
                "minItems": 3,
                "additionalItems": false
              }
            }
          },
          "required": [
            "paths"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "polygon"
      ]
    },
    "tagAnnotation": {
      "description": "A Tag annotation",
      "type": "object",
      "properties": {
        "tag": {
          "description": "A Tag annotation's details",
          "type": "object",
          "properties": {

          },
          "required": [],
          "additionalProperties": false
        }
      },
      "required": [
        "tag"
      ]
    },
    "lineAnnotation": {
      "description": "A Line annotation",
      "type": "object",
      "properties": {
        "line": {
          "description": "A Line annotation's details",
          "type": "object",
          "properties": {
            "path": {
              "description": "A list of points defining the line",
              "type": "array",
              "items": {
                "description": "A point",
                "type": "object",
                "properties": {
                  "x": {
                    "description": "X coordinate of the point",
                    "type": "number"
                  },
                  "y": {
                    "description": "Y coordinate of the point",
                    "type": "number"
                  }
                },
                "required": [
                  "x",
                  "y"
                ],
                "additionalProperties": false
              },
              "minItems": 2
            }
          },
          "required": [
            "path"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "line"
      ]
    },
    "keypointAnnotation": {
      "description": "A Keypoint annotation",
      "type": "object",
      "properties": {
        "keypoint": {
          "description": "A Keypoint annotation's details",
          "type": "object",
          "properties": {
            "x": {
              "description": "X coordinate of the keypoint",
              "type": "number"
            },
            "y": {
              "description": "Y coordinate of the keypoint",
              "type": "number"
            }
          },
          "required": [
            "x",
            "y"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "keypoint"
      ]
    },
    "ellipseAnnotation": {
      "description": "A Ellipse annotation",
      "type": "object",
      "properties": {
        "ellipse": {
          "description": "An Ellipse annotation's details",
          "type": "object",
          "properties": {
            "center": {
              "description": "A point defining the center of the ellipse",
              "type": "object",
              "properties": {
                "x": {
                  "description": "X coordinate of the center",
                  "type": "number"
                },
                "y": {
                  "description": "Y coordinate of the center",
                  "type": "number"
                }
              },
              "required": [
                "x",
                "y"
              ],
              "additionalProperties": false
            },
            "radius": {
              "description": "A point defining the horizontal and vertical radiuses of the ellipse",
              "type": "object",
              "properties": {
                "x": {
                  "description": "Horizontal radius",
                  "type": "number"
                },
                "y": {
                  "description": "Vertical radius",
                  "type": "number"
                }
              },
              "required": [
                "x",
                "y"
              ],
              "additionalProperties": false
            },
            "angle": {
              "description": "Angle of rotation of the ellipse",
              "type": "number"
            }
          },
          "required": [
            "center",
            "radius",
            "angle"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ellipse"
      ]
    },
    "skeletonAnnotation": {
      "description": "A Skeleton annotation",
      "type": "object",
      "properties": {
        "skeleton": {
          "description": "A Skeleton annotation's details",
          "type": "object",
          "properties": {
            "nodes": {
              "description": "A list of skeleton joints",
              "type": "array",
              "items": {
                "description": "A skeleton joint",
                "type": "object",
                "properties": {
                  "x": {
                    "description": "X coordinate of the joint",
                    "type": "number"
                  },
                  "y": {
                    "description": "Y coordinate of the joint",
                    "type": "number"
                  },
                  "occluded": {
                    "description": "Whether the joint is occluded",
                    "type": "boolean"
                  },
                  "name": {
                    "description": "Name of the joint",
                    "type": "string"
                  }
                },
                "required": [
                  "x",
                  "y",
                  "occluded",
                  "name"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "nodes"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "skeleton"
      ]
    },
    "tableAnnotation": {
      "description": "A Table annotation",
      "type": "object",
      "properties": {
        "table": {
          "description": "A Table annotation's details",
          "type": "object",
          "properties": {
            "bounding_box": {
              "$ref": "#/$defs/boundingBox"
            },
            "cells": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "row": {
                    "type": "integer"
                  },
                  "col": {
                    "type": "integer"
                  },
                  "row_span": {
                    "type": "integer"
                  },
                  "col_span": {
                    "type": "integer"
                  },
                  "is_header": {
                    "type": "boolean"
                  },
                  "bounding_box": {
                    "$ref": "#/$defs/boundingBox"
                  }
                },
                "required": [
                  "id",
                  "row",
                  "col",
                  "row_span",
                  "col_span"
                ]
              }
            }
          },
          "required": [
            "cells"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "table"
      ]
    },
    "stringAnnotation": {
      "description": "A String annotation",
      "type": "object",
      "properties": {
        "string": {
          "description": "A String annotation's details",
          "type": "object",
          "properties": {
            "sources": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "ranges": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "integer"
                    }
                  }
                },
                "required": [
                  "id"
                ]
              }
            }
          },
          "required": [
            "sources"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "string"
      ]
    },
    "graphAnnotation": {
      "description": "A Graph annotation",
      "type": "object",
      "properties": {
        "graph": {
          "description": "A Graph annotation's details",
          "type": "object",
          "properties": {
            "edges": {
              "description": "List of Graph edges",
              "type": "array",
              "items": {
                "description": "Graphs edge object",
                "type": "object",
                "properties": {
                  "start": {
                    "type": "string"
                  },
                  "end": {
                    "type": "string"
                  }
                },
                "required": [
                  "start",
                  "end"
                ]
              }
            },
            "nodes": {
              "description": "List of Graph nodes",
              "type": "array",
              "items": {
                "description": "Graphs node object",
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            }
          },
          "required": [
            "edges",
            "nodes"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "graph"
      ]
    },
    "instanceIdSubAnnotation": {
      "description": "A InstanceId sub-annotation",
      "type": "object",
      "properties": {
        "instance_id": {
          "description": "A InstanceId sub-annotation's details",
          "type": "object",
          "properties": {
            "value": {
              "type": "integer"
            }
          },
          "required": [
            "value"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "instance_id"
      ]
    },
    "attributesSubAnnotation": {
      "description": "An Attributes sub-annotation",
      "type": "object",
      "properties": {
        "attributes": {
          "description": "An Attributes sub-annotation's details",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "attributes"
      ]
    },
    "textSubAnnotation": {
      "description": "A Text sub-annotation",
      "type": "object",
      "properties": {
        "text": {
          "description": "A Text sub-annotation's details",
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            }
          },
          "required": [
            "text"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "text"
      ]
    },
    "inferenceSubAnnotation": {
      "description": "A Inference sub-annotation",
      "type": "object",
      "properties": {
        "inference": {
          "description": "A Inference sub-annotation's details",
          "type": "object",
          "properties": {
            "confidence": {
              "type": "number"
            },
            "model": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "type"
              ]
            }
          },
          "required": [
            "confidence",
            "model"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "inference"
      ]
    },
    "directionalVectorSubAnnotation": {
      "description": "A DirectionalVector sub-annotation",
      "type": "object",
      "properties": {
        "directional_vector": {
          "description": "A DirectionalVector sub-annotation's details",
          "type": "object",
          "properties": {
            "angle": {
              "type": "number"
            },
            "length": {
              "type": "number"
            }
          },
          "required": [
            "angle",
            "length"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "directional_vector"
      ]
    },
    "measuresSubAnnotation": {
      "description": "A Measures sub-annotation",
      "type": "object",
      "properties": {
        "measures": {
          "description": "A Measures sub-annotation's details",
          "type": "object",
          "properties": {
            "unit": {
              "type": "object",
              "properties": {
                "x": {
                  "type": "number"
                },
                "y": {
                  "type": "number"
                }
              },
              "required": [
                "x",
                "y"
              ]
            },
            "delta": {
              "type": "object",
              "properties": {
                "x": {
                  "type": "number"
                },
                "y": {
                  "type": "number"
                }
              },
              "required": [
                "x",
                "y"
              ]
            }
          },
          "required": [
            "unit",
            "delta"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "measures"
      ]
    },
    "annotationDetail": {
      "allOf": [
        {
          "if": {
            "required": [
              "polygon"
            ]
          },
          "then": {
            "$ref": "#/$defs/polygonAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "bounding_box"
            ]
          },
          "then": {
            "$ref": "#/$defs/boundingBoxAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "tag"
            ]
          },
          "then": {
            "$ref": "#/$defs/tagAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "line"
            ]
          },
          "then": {
            "$ref": "#/$defs/lineAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "keypoint"
            ]
          },
          "then": {
            "$ref": "#/$defs/keypointAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "ellipse"
            ]
          },
          "then": {
            "$ref": "#/$defs/ellipseAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "skeleton"
            ]
          },
          "then": {
            "$ref": "#/$defs/skeletonAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "table"
            ]
          },
          "then": {
            "$ref": "#/$defs/tableAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "string"
            ]
          },
          "then": {
            "$ref": "#/$defs/stringAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "graph"
            ]
          },
          "then": {
            "$ref": "#/$defs/graphAnnotation"
          }
        }
      ]
    },
    "annotationSubs": {
      "allOf": [
        {
          "if": {
            "required": [
              "instance_id"
            ]
          },
          "then": {
            "$ref": "#/$defs/instanceIdSubAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "attributes"
            ]
          },
          "then": {
            "$ref": "#/$defs/attributesSubAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "text"
            ]
          },
          "then": {
            "$ref": "#/$defs/textSubAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "inference"
            ]
          },
          "then": {
            "$ref": "#/$defs/inferenceSubAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "directional_vector"
            ]
          },
          "then": {
            "$ref": "#/$defs/directionalVectorSubAnnotation"
          }
        },
        {
          "if": {
            "required": [
              "measures"
            ]
          },
          "then": {
            "$ref": "#/$defs/measuresSubAnnotation"
          }
        }
      ]
    },
    "annotationBase": {
      "description": "Base annotation object",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the annotation label",
          "type": "string"
        },
        "id": {
          "description": "ID of the annotation on Darwin",
          "type": "string"
        },
        "slot_names": {
          "description": "Slot names this annotation is associated with",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "annotators": {
          "description": "List of users who created or modified this annotation. Included when authorship information is requested (default for webhooks, optional for exports).",
          "type": "array",
          "items": {
            "$ref": "#/$defs/annotationActor"
          }
        },
        "reviewers": {
          "description": "List of users who reviewed this annotation. Included when authorship information is requested (default for webhooks, optional for exports).",
          "type": "array",
          "items": {
            "$ref": "#/$defs/annotationActor"
          }
        },
        "only_keyframes": {
          "description": "Indicates if non keyframes are skipped",
          "type": "boolean"
        }
      },
      "required": [
        "name"
      ]
    },
    "imageAnnotation": {
      "allOf": [
        {
          "$ref": "#/$defs/annotationBase"
        },
        {
          "$ref": "#/$defs/annotationDetail"
        },
        {
          "$ref": "#/$defs/annotationSubs"
        },
        {
          "$ref": "#/$defs/annotationBaseConsumeAll"
        },
        {
          "$ref": "#/$defs/annotationDetailConsumeAll"
        },
        {
          "$ref": "#/$defs/annotationSubsConsumeAll"
        },
        {
          "$ref": "#/$defs/annotationProperties"
        }
      ],
      "unevaluatedProperties": false
    },
    "sequenceAnnotation": {
      "allOf": [
        {
          "$ref": "#/$defs/annotationBase"
        },
        {
          "$ref": "#/$defs/annotationBaseConsumeAll"
        },
        {
          "$ref": "#/$defs/annotationSequenceBaseConsumeAll"
        },
        {
          "$ref": "#/$defs/annotationProperties"
        }
      ],
      "unevaluatedProperties": false,
      "description": "Sequence annotation object",
      "type": "object",
      "properties": {
        "ranges": {
          "description": "Ranges of frames where annotation is present",
          "type": "array",
          "items": {
            "description": "Range of frames where annotation is present",
            "type": "array",
            "items": {
              "type": "integer"
            },
            "minItems": 2,
            "maxItems": 2
          }
        },
        "hidden_areas": {
          "description": "Ranges of frames where annotation is hidden",
          "type": "array",
          "items": {
            "description": "Range of frames where annotation is hidden",
            "type": "array",
            "items": {
              "type": "integer"
            },
            "minItems": 2,
            "maxItems": 2
          }
        },
        "interpolated": {
          "description": "Indicates if the annotations were interpolated",
          "type": "boolean"
        },
        "interpolate_algorithm": {
          "description": "Algorithm used to interpolate annotations between keyframes",
          "type": "string"
        },
        "frames": {
          "type": "object",
          "patternProperties": {
            "^[0-9]+$": {
              "allOf": [
                {
                  "$ref": "#/$defs/annotationDetail"
                },
                {
                  "$ref": "#/$defs/annotationSubs"
                },
                {
                  "$ref": "#/$defs/annotationDetailConsumeAll"
                },
                {
                  "$ref": "#/$defs/annotationSubsConsumeAll"
                },
                {
                  "type": "object",
                  "properties": {
                    "keyframe": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "keyframe"
                  ]
                }
              ],
              "unevaluatedProperties": false
            }
          }
        }
      },
      "required": [
        "frames",
        "ranges"
      ]
    },
    "annotationActor": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "full_name": {
          "type": "string"
        },
        "updated_at": {
          "description": "ISO 8601 timestamp of when the annotation was last modified. Only included when authorship information is requested.",
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "full_name",
        "email"
      ]
    },
    "annotationSequenceBaseConsumeAll": {
      "description": "This is a catch all schema that is supposed to 'consume' all expected properties even if they fail actual validation. This is to improve error reporting due to 'unevaluatedProperties' resolving before any more specific errors are reported.",
      "properties": {
        "frames": {

        },
        "ranges": {

        },
        "interpolated": {

        },
        "interpolate_algorithm": {

        }
      }
    },
    "annotationBaseConsumeAll": {
      "description": "This is a catch all schema that is supposed to 'consume' all expected properties even if they fail actual validation. This is to improve error reporting due to 'unevaluatedProperties' resolving before any more specific errors are reported.",
      "properties": {
        "annotators": {

        },
        "reviewers": {

        },
        "id": {

        },
        "name": {

        },
        "slot_names": {

        },
        "only_keyframes": {

        }
      }
    },
    "annotationDetailConsumeAll": {
      "description": "This is a catch all schema that is supposed to 'consume' all expected properties even if they fail actual validation. This is to improve error reporting due to 'unevaluatedProperties' resolving before any more specific errors are reported.",
      "properties": {
        "polygon": {

        },
        "bounding_box": {

        },
        "tag": {

        },
        "line": {

        },
        "keypoint": {

        },
        "ellipse": {

        },
        "skeleton": {

        },
        "table": {

        },
        "string": {

        },
        "graph": {

        }
      }
    },
    "annotationSubsConsumeAll": {
      "description": "This is a catch all schema that is supposed to 'consume' all expected properties even if they fail actual validation. This is to improve error reporting due to 'unevaluatedProperties' resolving before any more specific errors are reported.",
      "properties": {
        "instance_id": {

        },
        "text": {

        },
        "attributes": {

        },
        "inference": {

        },
        "directional_vector": {

        },
        "measures": {

        }
      }
    },
    "annotationProperties": {
      "description": "Properties object",
      "type": "object",
      "properties": {
        "properties": {
          "description": "List of linked properties",
          "type": "array",
          "items": {
            "description": "Property value object",
            "type": "object",
            "properties": {
              "frame_index": {
                "description": "Frame index of the property. For image annotations always 0.",
                "type": "integer"
              },
              "name": {
                "description": "Name of the property",
                "type": "string"
              },
              "value": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "frame_index",
              "name",
              "value"
            ]
          }
        }
      }
    },
    "workflowEvent": {
      "description": "Event that happened in the workflow",
      "type": "object",
      "properties": {
        "type": {
          "description": "Type of the event",
          "enum": [
            "workflow_stage_transitioned",
            "workflow_stage_set"
          ]
        },
        "actor": {
          "description": "Event actor",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "email": {
              "type": "string"
            },
            "full_name": {
              "type": "string"
            }
          },
          "required": [
            "full_name",
            "email"
          ]
        }
      },
      "required": [
        "type",
        "actor"
      ],
      "allOf": [
        {
          "if": {
            "properties": {
              "type": {
                "const": "workflow_stage_transitioned"
              }
            }
          },
          "then": {
            "properties": {
              "edge": {
                "type": "string"
              },
              "source_stage_id": {
                "type": "string"
              },
              "target_stage_id": {
                "type": "string"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "workflow_stage_set"
              }
            }
          },
          "then": {
            "properties": {
              "target_stage_id": {
                "type": "string"
              }
            }
          }
        }
      ]
    }
  }
}

Required Darwin JSON 2.0 Fields

To construct Darwin JSON 2.0 files for import, many of the fields in the schema are not required. Below is a sample unannotated Darwin JSON 2.0 file with only the required fields:

{  
  "version": "2.0",  
  "schema_ref": "<https://darwin-public.s3.eu-west-1.amazonaws.com/darwin_json/2.0/schema.json",  
  "item": {  
    "name": "item_name.jpg",  
    "path": "/"  
  },  
  "annotations": []  
}

Metadata

The metadata.json file is a special file located in the .v7 folder at the root of the export. It contains information about annotation classes and properties used across all exported annotations. If the team selected for annotations import doesn't have a class or property linked to an annotation, the definitions in this file are used to create those entities.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Darwin JSON Format for annotation classes used across annotations",
  "type": "object",
  "properties": {
    "version": {
      "description": "The version of this Darwin JSON document.",
      "type": "string",
      "enum": [
        "2.0"
      ]
    },
    "schema_ref": {
      "description": "URL to JSON schema describing this document.",
      "type": "string"
    },
    "classes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "description": "Main type",
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "color": {
            "description": "Color of the class",
            "type": "string"
          },
          "sub_types": {
            "type": "array",
            "description": "List of sub types",
            "items": {
              "type": "string"
            }
          },
          "properties": {
            "type": "array",
            "description": "List of properties",
            "items": {
              "ref": "#/$defs/property"
            }
          }
        },
        "required": [
          "name",
          "type",
          "description",
          "color",
          "sub_types",
          "properties"
        ]
      }
    }
  },
  "required": [
    "classes"
  ],
  "additionalProperties": false,
  "$defs": {
    "property": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "required": {
          "type": "boolean"
        },
        "property_values": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string"
              },
              "color": {
                "type": "string"
              }
            },
            "required": [
              "value",
              "color"
            ]
          }
        }
      },
      "required": [
        "name",
        "type",
        "required",
        "property_values"
      ]
    }
  }
}