annotation_swagger.yaml

# OAPI Specification for the annotation tool service
openapi: 3.0.0
info:
  title: Annotation Service
  version: 1.0.0
paths:

  /tasks/{taskId}:
    get:
      summary: Get information about a task
      operationId: getTaskInfo
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Task information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskInfo"
        "404":
          description: Task not found

  /tasks:
    get:
      summary: Gets the tasks assigned to the authenticated user
      operationId: getTasksInfo
      parameters:
        - name: state
          in: query
          description: The state of the tasks to fetch
          schema:
            $ref: "#/components/schemas/TaskState"
      responses:
        "200":
          description: The list of tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TasksInfo"
    post:
      summary: Create a new task
      operationId: createTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewTask"
      responses:
        "200":
          description: Task received and stored successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskInfo"
        "400":
          description: Bad request, invalid task data
        "500":
          description: Internal server error, failed to create task store or to insert task data or to create Jira issue

  /tasks/transition/{endState}/{taskId}:
    post:
      summary: Transition a task to its new state
      operationId: beginTaskTransition
      parameters:
        - name: endState
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/TaskState"
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransitionUpdate"
      responses:
        "200":
          description: Task transitioned successfully

components:
  schemas:
    TaskInfo:
      type: object
      properties:
        task_id:
          type: string
        experiment_name:
          type: string
        creator_id:
          type: string
        instructions:
          type: string
        left_chat_id:
          type: string
        right_chat_id:
          type: string
        primary_chat_id:
          type: string
        state:
          $ref: "#/components/schemas/TaskState"
        display_mode:
          type: string
          description: The mode in which the chat should be displayed to the annotator
        duplicate_status:
          type: object
          additionalProperties:
            type: string
            format: date-time
            nullable: true
        metadata:
          type: object
          description: Metadata to be stored with the task and used by either the experiment or the front-end
        annotation_ontology:
          $ref: "#/components/schemas/AnnotationOntology"
          description: The annotations to be displayed during annotation for this task

    TasksInfo:
      type: object
      properties:
        tasks:
          type: array
          description: The list of tasks assigned to the user
          items:
            $ref: "#/components/schemas/TaskInfo"

    NewTask:
      type: object
      properties:
        experiment_name:
          type: string
          description: A unique name for the experiment being performed. E.g. ${GOAL}-${CREATOR_EMAIL}-{$DATE}
        creator_id:
          type: string
          description: The user id of the person who is responsible for creating the task
        instructions:
          type: string
          description: Instructions to be read by the annotator before performing the task
        display_mode:
          type: string
          description: The mode in which the chat should be displayed to the annotator
        source_chat_id:
          type: string
          description: The ChatId of the chat snippet to copy from
        source_start_turn_id:
          type: string
          description: The TurnId at the end of the snippet to copy from
        source_end_turn_id:
          type: string
          description: The TurnId at the end of the snippet to copy from
        source_chat_owner_id:
          type: string
          description: The user id of the person who owns the source chat
        annotation_ontology:
          $ref: "#/components/schemas/AnnotationOntology"
          description: The ontology to be used for annotation
        metadata:
          type: object
          description: Metadata to be stored with the task and used by either the experiment or the front-end

    TaskState:
      type: string
      enum:
        - created
        - inprogress
        - done

    Candidate:
      type: object
      properties:
        raw_content:
          type: string
          description: The text of the message
        metadata:
          type: object
          description: A dictionary of additional metadata

    SingleTurn:
      type: object
      properties:
        candidates:
          type: array
          description: A list of candidates for the turn
          items:
            $ref: "#/components/schemas/Candidate"
        is_human:
          type: boolean
          description: Whether the message was sent by a human or a character
        author_name:
          type: string
          description: The display name of the entity who sent the message

    NewChat:
      type: object
      properties:
        turns:
          type: array
          description: The ordered list of all messages in the chat
          items:
            $ref: "#/components/schemas/SingleTurn"

    NewTaskWithChat:
      type: object
      properties:
        task:
          $ref: "#/components/schemas/NewTask"
          description: The task to be created to hold the chat
        chat:
          $ref: "#/components/schemas/NewChat"
          description: The chat to be created for the task

    TransitionUpdate:
      type: object
      properties:
        comment:
          type: string
          description: An optional comment to add to the issue
        assignee:
          type: string
          description: If true then the issue will be assigned to one of the default users

    AnnotationOntology:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: "#/components/schemas/AnnotationCategory"
          description: Named categories of annotations in the order they will appear in the user interface
        questions:
          type: array
          items:
            type: string
          description: A list of questions to be asked of the annotator

    AnnotationCategory:
      type: object
      properties:
        name:
          type: string
          description: The name of the category as displayed in the user interface
        annotations:
          type: array
          items:
            $ref: "#/components/schemas/AnnotationType"
          description: A list of annotations that are displayed under this category

    AnnotationType:
      type: object
      properties:
        label:
          type: string
          description: The label for the annotation as stored in the data warehouse
        options:
          type: object
          description: A JSON object of options for the annotation