공통 어노테이터 스키마

적용 범위

본 문서는 Datamaker의 모든 어노테이터(이미지, 비디오, 텍스트, 프롬프트, PCD 등)가 공통적으로 따라야 하는 데이터 모델을 정의합니다.

각 어노테이터별 스펙은 이 스키마를 상속하고, 도구별(툴별) 고유 필드를 추가로 확장합니다.

핵심 원칙

classification 구조는 tool(도구)와 무관하며, 관리자(운영자) 페이지에서 직접 정의한 class, attributes, options로 구성됩니다.
attributes, options 등 모든 하위 구조 역시 사용자가 직접 정의합니다.
실제 어노테이션 데이터의 classification 필드는 트리 구조를 flatten(평탄화)한 key-value 쌍으로 저장됩니다.
특정 class가 선택된 경우, 필수 하위 속성(종속성)은 프로젝트별 dm-schema 확장 JSON Schema로 관리됩니다.

전체 구조 개요 (Mermaid)

flowchart TD
    Schema["관리자 정의 분류 스키마 (트리)"]
    Data["실제 어노테이션 데이터 (Flatten)"]
    Schema -->|Flatten 규칙| Data
    Schema -->|종속성 규칙| JSONSchema["dm-schema 확장 JSON Schema"]
    Data -->|유효성 검증| JSONSchema

공통 데이터 모델

4.1 최상위 구조

모든 어노테이션 작업은 하나의 JSON 객체로 저장되며, 최상위 키는 어노테이터 종류와 관계없이 동일합니다.

키	타입	설명
`extra`	`Record<string, unknown>`	에셋별 메타데이터
`relations`	`Record<string, RelationItem[]>`	어노테이션 간 관계
`annotations`	`Record<string, AnnotationBase[]>`	에셋 단위의 어노테이션 목록
`annotationsData`	`Record<string, AnnotationDataItem[]>`	어노테이션 실제 좌표/데이터
`annotationGroups`	`Record<string, AnnotationGroupItem[]>`	어노테이션 그룹화
`assignmentId`	`string`	작업 식별자

4.2 공통 객체 정의

AnnotationBase

필드	타입	설명
`id`	`string`	어노테이션 고유 ID
`tool`	`string`	사용된 툴 이름
`isLocked`	`boolean`	편집 잠금 여부
`isVisible`	`boolean`	화면 표시 여부
`classification`	`Classification \| null`	분류 정보

RelationItem (관계 객체)

필드명	타입	설명
`id`	string	관계(엣지) 고유 ID
`tool`	string	항상 “relation”
`isLocked`	boolean	관계 편집 잠금 여부
`isVisible`	boolean	관계 표시 여부
`annotationId`	string	관계의 출발(소스) 어노테이션 ID
`classification`	object	관계에 부여된 분류 정보(선택, flatten)
`targetAnnotationId`	string	관계의 도착(타겟) 어노테이션 ID

relations 필드 구조:

타입: Record<string, RelationItem[]> (key: asset id, value: RelationItem 배열)
한 asset(예: image_1) 내에서 여러 관계를 배열로 저장

relations 실제 데이터 예시:

"relations": {
  "image_1": [
    {
      "id": "CvNVkv7pEcnjBiaEDrbO",
      "tool": "relation",
      "isLocked": false,
      "isVisible": true,
      "annotationId": "CvNVkv7pEc",
      "classification": {
        "car": "sedan",
        "class": "object_type"
      },
      "targetAnnotationId": "njBiaEDrbO"
    },
    {
      "id": "njBiaEDrbO9Vztyud5WT",
      "tool": "relation",
      "isLocked": false,
      "isVisible": true,
      "annotationId": "njBiaEDrbO",
      "classification": {
        "car": "sedan",
        "class": "object_type"
      },
      "targetAnnotationId": "9Vztyud5WT"
    }
    // ...
  ]
}

설명:

annotationId는 관계의 시작점(출발 어노테이션 ID), targetAnnotationId는 끝점(도착 어노테이션 ID)
classification은 관계 자체에 부여된 속성(예: 관계 타입, 의미 등)으로, annotation의 classification과 동일한 flatten 구조
관계(RelationItem)는 객체 간 연결, 계층, 의미론적 관계(예: 부모-자식, 파트-전체 등) 표현에 사용

AnnotationGroupItem (그룹 객체)

필드명	타입	설명
id	string	그룹 고유 ID
tool	string	항상 “annotationGroup”
isLocked	boolean	그룹 편집 잠금 여부
annotationList	Array	그룹에 속한 어노테이션 목록
classification	object	그룹 자체에 부여된 분류 정보(flatten)

GroupMemberItem
- annotationId: string (그룹에 속한 어노테이션 ID)
- children: array (서브 그룹/계층 구조, 현재 예시에서는 항상 빈 배열)

annotationGroups 실제 데이터 예시:

"annotationGroups": {
  "image_1": [
    {
      "id": "Bywx5sr5HA",
      "tool": "annotationGroup",
      "isLocked": false,
      "annotationList": [
        { "children": [], "annotationId": "njBiaEDrbO" },
        { "children": [], "annotationId": "FdE6x5Hy6L" },
        { "children": [], "annotationId": "S1yHsB6psd" }
      ],
      "classification": {
        "car3": "suv",
        "class": "object_type"
      }
    },
    {
      "id": "wmRPPexDkD",
      "tool": "annotationGroup",
      "isLocked": false,
      "annotationList": [
        { "children": [], "annotationId": "CvNVkv7pEc" },
        { "children": [], "annotationId": "9Vztyud5WT" }
      ],
      "classification": {
        "car3": "suv",
        "class": "object_type"
      }
    }
  ]
}

설명:

annotationGroups는 한 asset(예: image_1) 내에서 여러 그룹을 배열로 저장합니다.
각 그룹은 여러 어노테이션(annotationId)을 포함할 수 있으며, 계층 구조(children)를 지원합니다.
그룹 자체에도 classification(분류 정보, flatten 구조)을 부여할 수 있습니다.
그룹의 용도: 객체 집합(레이어), 계층적 구조, 복합 어노테이션 관리 등.

AnnotationDataItem

필드	타입	설명
`frameIndex?`	`number`	프레임 번호(비디오·타임시리즈 등)
`section?`	`{ startFrame: number; endFrame: number }`	프레임 구간 정보
`input?`	`string`	프롬프트 입력
`output?`	`string`	모델 출력

분류(classification) 구조

5.1 분류 스키마(관리자 정의, 트리)

필드명	타입	설명
id	string	내부 식별자
code	string	키 이름, flatten시 key로 사용
name	string	사용자 표시명
value	string	(주로 색상 등)
attributes	array	하위 속성(재귀 구조)
options	array	선택지(옵션, code/name/color)
widget	string	입력 방식(single/multi 등)
is_required	boolean	필수 여부
is_default	boolean	기본값 여부
customFields	object	확장 필드

5.2 분류 데이터(flatten 구조)

트리 구조의 각 노드는 key-value 쌍으로 평탄화
key 이름은 code 값, value는 선택된 값
항상 1-depth의 key-value 쌍 (중첩 구조 없음)
모든 값은 string, number, boolean 등 단일 값

예시 필드명	예시 값	설명
class	”car”	선택된 클래스
type	”suv”	class에 종속된 하위 속성
color	”#4b31b8”	추가 속성
custom_property	”값”	확장 필드

5.3 타입 정의(TypeScript)

type ClassificationFlat = {
  [code: string]: string | number | boolean;
}

// 예시
const example: ClassificationFlat = {
  class: "car",
  type: "suv",
  color: "#4b31b8",
  custom_property: "값"
};

5.4 종속성 및 유효성(JSON Schema)

특정 class(예: “car”)가 선택될 때 반드시 포함해야 하는 하위 속성/옵션은 dm-schema 확장 JSON Schema에서 아래와 같이 정의합니다.

{
  "type": "object",
  "properties": {
    "class": { "type": "string", "enum": ["car", "person"] },
    "type": { "type": "string", "enum": ["suv", "sedan"] }
  },
  "required": ["class"],
  "dependencies": {
    "class": {
      "oneOf": [
        {
          "properties": { "class": { "const": "car" } },
          "required": ["type"]
        },
        {
          "properties": { "class": { "const": "person" } }
          // person일 때는 type 미필수 등
        }
      ]
    }
  }
}

입력 데이터(classification flatten 구조)가 위 schema의 규칙을 반드시 충족해야 하며, 누락된 필수 속성, 잘못된 값 등은 validation 에러로 처리됩니다.

5.5 예시(관리자 정의 → 실제 데이터)

{
  "class": "car",
  "type": "suv",
  "color": "#4b31b8",
  "custom_property": "값"
}

5.6 Mermaid/시퀀스 다이어그램

sequenceDiagram
    participant 관리자 as "관리자"
    participant 어노테이터 as "어노테이터"
    participant 데이터 as "데이터"

    관리자->>어노테이터: 분류 스키마 정의
    어노테이터->>데이터: 분류 데이터 생성
    데이터->>관리자: 분류 데이터 전송
    관리자->>데이터: 유효성 검증

5.7 참고 및 확장

분류 데이터는 다양한 확장 필드를 가질 수 있습니다.
분류 데이터는 다양한 형식으로 저장될 수 있습니다. | attributes | Record<string, unknown> | 추가 속성 |

2.3 RelationItem

필드	타입	설명
`id`	`string`	관계 ID
`srcId`	`string`	출발 어노테이션 ID
`dstId`	`string`	도착 어노테이션 ID
`type`	`string`	관계 타입(예: part_of)

2.4 AnnotationGroupItem

필드	타입	설명
`id`	`string`	그룹 ID
`memberIds`	`string[]`	그룹에 속한 어노테이션 ID 목록
`name`	`string`	그룹 이름(선택)

2.5 AnnotationDataItem

필드	타입	설명
`frameIndex?`	`number`	프레임 번호(비디오·타임시리즈 등)
`section?`	`{ startFrame: number; endFrame: number }`	프레임 구간 정보
`input?`	`string`	프롬프트 입력
`output?`	`string`	모델 출력

확장 규칙

추가 필드: 어노테이터가 고유하게 필요한 필드는 tool 값으로 판별된 하위 스키마(개별 문서)에서만 정의합니다.
버전 관리: 필드 추가 시 루트에 schemaVersion(string)을 두고 SemVer 규칙을 따릅니다.
불변 데이터: 어노테이션 id는 생성 후 변경할 수 없습니다. 새 버전을 생성할 경우 새 ID를 발급합니다.

예시

{
  "assignmentId": "job-123",
  "extra": {
    "asset_001": { "textContent": "Lorem ipsum" }
  },
  "annotations": {
    "asset_001": [
      {
        "id": "ann-1",
        "tool": "named_entity",
        "isLocked": false,
        "isVisible": true,
        "classification": {
          "class": "some_class",
          ["some_attribute"]: [string | number | boolean | array]
        }
      }
    ]
  },
  "relations": {},
  "annotationsData": {},
  "annotationGroups": {}
}