Specification.yaml

openapi: 3.0.0
info:
  title: Annotatron
  description: >-
    Annotatron describes, displays, processes, visualizes, and allows humans to annotate machine learning corpora.

    ## Definitions

    These terms have special meaning for Annotatron:


    _Application-global ID_:

    > Any user can access a resource using this identifier and get the same ID. This ID is used for most system objects used by _Staff_ and _Administrator_ users.


    _User-specific ID_:

    > Only the user who received the identifier can retrieve the resource. This is used for objects accessed by _Annotator_ and _Reviewer_ useres. You can translate these to an _Application-global ID_ using the `/auth/id` end-point.

  version: 0.1.0

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

tags:
  - name: annotation
    description: >-
      Annotations are what we're trying to derive from Annotatron.
  - name: asset
    description: >-

      `Asset`s are indivisable, immutable pieces of content which you can annotate as part of a corpus.


      Each `Asset` can be part of more than one corpus, for example a database of photos can be annotated
      with age in one `Corpus`, and expression in another.

  - name: assignment
    description: >-
      `Assignments` are `Question`s about `Asset`s delivered to humans, and approved by `Reviewer`.
  - name: auth
    description: >-
      This tag collects API methods which are used for authentication, authorization, and anything to do with logging in, logging out, general security stuff.
  - name: conf
    description: >-
      This tag collects endpoints which are used to control the system.
  - name: corpus
    description: >-
      `Asset`s are stored in `Corpus` collections, which are used to organize datasets for annotation and training.
      Corpora collect and organize Assets to create a dataset used for annotation and training.
  - name: question
    description: >-
      `Question`s in Annotatron are prompts given to a human. Humans give the response, and it's recorded for later aggreation. Typically,
      multiple Annotators will respond and the resulting Annotation will be summarized for export.

  - name: needsImplementation
    description: >-
      These are endpoints which are defined, but not implemented.

  - name: needsTesting
    description: >-
      These are endpoints which need test coverage

paths:

  /conf/initialUser:
    get:
      tags:
        - conf
        - auth
      description: >-
        Checks whether this Annotatron instances requires initial set-up or not. Returns false if everything's normal. No Authorization is needed.

      operationId: checkNeedsSetup
      responses:
        200:
          description: Successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigurationResponse"
        402:
          description: Internal error

    post:
      operationId: createInitialUser
      tags:
        - conf
        - auth
      description: >-
        Creates the initial, primary user that will administer the system.

        * The `role` field will be automatically set to `Administrator`.

        No authorization key is needed.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUserRequest'
      responses:
        200:
          description: "Successful."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /auth/token:

    delete:
      operationId: deleteAuthToken
      tags:
        - auth
        - needsTesting
      description: >-
        Signs the current user out.
      responses:
        202:
          description: "Deleted"

    post:
      operationId: createAuthToken
      tags:
        - auth
      description: >-
        Logs the active `User` in (if possible), and returns an authentication token.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        200:
          description: "Successful."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        403:
          description: "Login unsuccessful."

  /auth/whoAmI:
    get:
      tags:
        - auth
      operationId: getWhoIAm
      description: >-
        Redirects to a resource that describes the currently signed in user.
        Returns an object with the currently-signed in User details.
      responses:
        302:
          description: "Successful."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        202:
          description: "Not logged in."

  /auth/users/{userId}:
    get:
      tags:
        - auth
      operationId: getUserDetails
      summary: Retrieve information about an Annotatron user.
      description: >-
        If called by an Administrator or Staff user, returns information about a specified user.
        If called by any other user, information about their account will be presented, so long as `userId` matches the current user.
      parameters:
        - name: userId
          in: path
          schema:
            type: integer
            format: int64
          required: true
          description: >-
            Application-global identifier for the user.
      responses:
        200:
          description: "Successful"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /auth/users/{userId}/password:
    put:
      tags:
        - auth
      operationId: changeUserPassword
      summary: Change or reset a password on an account
      description: >-
        * If called by an Administrator, resets the current password on a User's account.
          The account holder will be asked to set a new password the next time they log in.
        * If called by a user, `oldPassword` must be present and match the existing password
          set for the account.
        * All current login tokens will be invalidated.
      parameters:
        - name: userId
          in: path
          schema:
            type: integer
            format: int64
          required: true
          description: >-
            Application-global identifier for the current user (if changing their password) or the target user (if an administrator is doing it).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetRequest'
      responses:
        202:
          description: "Accepted"
        403:
          description: "Password could not be changed due to mismatch"

  /auth/users:
    get:
      tags:
        - auth
      operationId: listUsers
      description: >-
        Retrieves all application-global user identifiers. Can be done by a `Staff` or higher.
      responses:
        200:
          description: "Successful"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                  format: int64
    post:
      operationId: createUser
      tags:
        - conf
        - auth
      description: >-
        Creates a new user. This can only be done by an `Administrator`.
      requestBody:
        content:
            application/json:
             schema:
              $ref: '#/components/schemas/NewUserRequest'

      responses:
        201:
          description: "Successful."

  /assignments/{corpusName}:
    post:
      operationId: createAssignment
      parameters:
        - name: corpusName
          in: path
          schema:
            type: string
          required: true
          description: >-
            Which Corpus we're inserting into.
      tags:
        - assignment
        - needsTesting
      description: >-
        Adds an `Assignment` to Annotatron, which links a `Question` about an `Asset` in a given `Corpus` to a `User`
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Assignment'
      responses:
        201:
          description: "Successful"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulInsert'

  /assignments/{assignmentId}/{action}:
    patch:
      tags:
        - assignment
        - needsImplementation
        - needsTesting
      operationId: submitAssignment
      description: >-
        This endpoint mutates an `Assignment`, causing it to change state. This can be to approve, reject, annotate or review it.

        When called by the user who's in the `assignedAnnotatorId` field, saves and validates the `response` field and sends it for review.

        When called by the user who's in the `assignedReviewerId` field, completes review.
      parameters:
        - name: assignmentId
          in: path
          schema:
            type: integer
            format: int64
          required: true
        - name: action
          in: path
          schema:
            type: string
            enum:
              - submit
              - approve
              - reject
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignmentResponse'
      responses:
        202:
          description: "Updated successfully"
        422:
          description: "Validation error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
  /assignments/{assignmentId}:
    get:
      operationId: getAssignment
      tags:
        - assignment
        - needsImplementation
        - needsTesting
      operationId: retrieveAssignmentHistory
      description: >-
        This endpoint retrieves the history and current state for an Assignment.

      parameters:
        - name: assignmentId
          in: path
          schema:
            type: integer
            format: in64
          required: true

      responses:
        200:
          description: "Successful"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AssignmentHistory"


  /assignments/{assignmentId}:
    get:
      operationId: getAssignment
      tags:
        - assignment
        - needsImplementation
        - needsTesting
      description: >-
        Retrieve the details of an `Assignment`.
      parameters:
        - name: assignmentId
          in: path
          schema:
            type: integer
            format: int64
          required: true
      responses:
        200:
          description: "Successful."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assignment"


  /assignments/byUser/{userId}:
    get:
      tags:
        - assignment
        - needsTesting
      operationId: listAssignmentsByUser
      description: >-
        Retrieve the `Assignments` assigned to a user.
      parameters:
        - name: userId
          in: path
          schema:
            type: integer
            format: int64
          required: true
      responses:
        200:
          description: "Available assignments."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserAssignments"

  /assignments/byCorpus/{corpusId}:
    get:
      tags:
        - assignment
        - needsTesting
      operationId: listAssignmentsByUser
      description: >-
        Retrieve the `Assignments` assigned to a user.
      parameters:
        - name: corpusId
          in: path
          schema:
            type: string
          required: true
      responses:
        200:
          description: "Available assignments."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserAssignments"

  /corpus/{corpusName}/assets/{assetName}:
    put:
      tags:
        - asset
      operationId: createAsset
      summary: Adds an `Asset` to a `Corpus`
      description: >-
        Inserts an `Asset` into Annotatron. No de-duplication is provided (use the `HEAD` method to check.) The `id` field is ignored.
      parameters:
      - in: path
        name: corpusName
        schema:
          type: string
        required: true
        description: The unique name of the `Corpus` that's being modified.
      - in: path
        name: assetName
        schema:
          type: string
        required: true
        description: The unique name of the `Asset` that's being deleted.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BinaryAssetUpload'
      responses:
        '201':
          description: Successfully created
    delete:
      tags:
        - asset
      summary: Deletes an `Asset` from a `Corpus`.
      operationId: deleteAssetWithId
      description: >-
        Deletes an asset, if possible, from Annotatron's database.

        * The Asset will only be deleted if it's not referenced by any Corpus objects.

        * The Asset's metadata and content may persist in storage, but will not be accessible.
      parameters:
        - in: path
          name: corpusName
          schema:
            type: string
          required: true
          description: The unique name of the `Corpus` that's being modified.
        - in: path
          name: assetName
          schema:
            type: string
          required: true
          description: The unique name of the `Asset` that's being deleted inside the `Corpus`.
      responses:
        202:
          description: Successfully deleted.
        422:
          description: Can't delete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataLossReason'
    get:
      tags:
        - asset
      summary: Retrieve information about an Asset
      operationId: getAssetInfoWithId
      description: >-
        Retrieves some metadata about the Asset, such as when it was uploaded.
      parameters:
        - in: path
          name: corpusName
          schema:
            type: string
          required: true
          description: The `id` of the `Corpus` that's being accessed.
        - in: path
          name: assetName
          schema:
            type: string
          required: true
          description: The unique name of the `Asset` inside the `Corpus`.
      responses:
        200:
          description: Asset details successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BinaryAssetDescription'

  /assets/{assetId}/content:
    get:
      tags:
        - asset
        - needsImplementation
      operationId: getAssetContentWithId
      description: >-
        Retrieves the bytes that make up an `Asset`.
      parameters:
        - in: path
          name: assetId
          schema:
            type: integer
            format: int64
          required: true
          description: The obfuscated id of the `Asset`. Retrieved from `BinaryAssetDescription.id`

      responses:
        200:
          description: Asset content successfully retrieved.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /corpus/{corpusName}/assets:
    get:
        tags:
          - corpus
          - asset
        operationId: getAssetsByCorpusId
        description: >-
          Retrieves the `Asset`s that make up a `Corpus`.
        parameters:
          - name: corpusName
            in: path
            required: true
            description: The identifier of the `Corpus` to look in.
            schema:
              type: string
        responses:
          200:
            description: Successful response
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Corpus"

  /corpus/{corpusName}/questions:
    post:
      operationId: createQuestion
      tags:
        - question
      description: >-
        Attaches a `Question` object to a an `Asset` in a `Corpus` for human
        annotation.
      parameters:
        - name: corpusName
          in: path
          required: true
          description: The identifier of the `Corpus` containing the `Asset`
          schema:
            type: string
        - name: assetName
          in: path
          required: true
          description: The identifier of the `Asset` to add the `Question` to.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Question"
      responses:
        201:
          description: "Successfully created."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessfulInsert"
    get:
      operationId: getQuestions
      tags:
        - question
      description: >-
        This retrieves a list of identifiers which map to `Questions` via the `questions/{id}` endpoint.
      parameters:
        - name: corpusName
          in: path
          required: true
          description: The identifier of the `Corpus` to link with.
          schema:
            type: string
      responses:
        200:
          description: A list of application-global question identifiers.
          content:
            application/json:
              schema:
                type: integer
                format: int64

  /corpus/{corpusName}/questions/{questionId}:
    get:
      operationId: getQuestion
      tags:
        - question
      description: >-
        This retrieves the full content of a `Question` associated with a corpus.

      parameters:
        - name: corpusName
          in: path
          required: true
          description: The identifier of the `Corpus` to link with.
          schema:
            type: string
        - name: questionId
          in: path
          required: true
          description: The application-global identifier of the `Question`.
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Question"
    delete:
      operationId: deleteQuestion
      tags:
        - question

      parameters:
        - name: corpusName
          in: path
          required: true
          description: The identifier of the `Corpus` to link with.
          schema:
            type: string
        - name: questionId
          in: path
          required: true
          description: The application-global identifier of the `Question`.
          schema:
            type: integer
            format: int64
      responses:
        202:
          description: "Accepted for deletion"



  /corpus/{corpusName}:
    get:
      tags:
        - corpus
      operationId: getCorpusById
      description: >-
        Retrieves details about a Corpus
      parameters:
        - name: corpusName
          in: path
          required: true
          description: The identifier of the `Corpus` to link with.
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Corpus"
  /corpus:
    get:
      tags:
        - corpus
      description: >-
        Retrieves a list of identifiers that correspond to current `Corpus` objects.
        These can be resolved into Corpus objects later via the `/corpus/{id}` endpoint.

      operationId: listAllCorpora
      parameters:
        - name: name
          schema:
            type: string
          in: query
          description: "Partially match corpora which contain this name."
      responses:
        200:
          description: A JSON array of `Corpus` identifiers.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    post:
      tags:
        - corpus
      operationId: createCorpus
      description: >-
        Adds a new `Corpus` to the database.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Corpus'
      responses:
        201:
          description: "Successfully created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessfulInsert"

components:
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
  schemas:

    AbstractAnnotation:
      type: object
      required:
        - kind
        - source
        - summaryCode
      properties:
        created:
          type: string
          format: datetime
        kind:
          type: string
          enum:
            - TimeSeriesSegmentationAnnotation
            - TimeSeriesRangeAnnotation
            - MultipleChoiceAnnotation
            - GenericJSONAnnotation
            - TextAnnotation
        source:
          type: string
          enum:
            - Reference
            - SystemGenerated
            - Human
            - Aggregated
        summaryCode:
          type: string


    AbstractQuestion:
      type: object
      required:
        - humanPrompt
        - kind
        - summaryCode
        - created
      properties:
        id:
          type: integer
          format: int64
          description: Ignored on upload.
        summaryCode:
          type: string
          description: >-
            This is a short string which is used by Annotatron to group responses for a given Asset, often from different Annotators.
          example: TRANSCRIPT
        humanPrompt:
          type: string
          description: >-
            This is the text presented to the user, e.g. if this field is set to
              > Is this transcription accurate?
            Then that is what will be presented to the user
          example: "Select all the animals in this picture."
        created:
          type: string
          format: datetime
        detailedAnnotationInstructions:
          description: >-
            Contains detailed annotation instructions, in CommonMark format.
          type: string
        annotationInstructions:
          description: >-
            Contains head-line annotation instructions, in CommonMark format.
          type: string
        kind:
          description: >-
            This must be set to the type of `Question` that this is.

            Valid values are:
              * `TimeSeriesSegmentationQuestion`
              * `TimeSeriesRangeQuestion`
              * `MultipleChoiceQuestion`
          type: string
        assets:
          description: >-
            This is a list of user-specific IDs which describe the `Asset`s which are going to be displayed for this question.
          type: array
          items:
              type: integer
              format: int64

    Annotation:
      oneOf:
        - $ref: "#/components/schemas/TimeSeriesSegmentationAnnotation"
        - $ref: "#/components/schemas/TimeSeriesRangeAnnotation"
        - $ref: "#/components/schemas/GenericJSONAnnotation"
        - $ref: "#/components/schemas/MultipleChoiceAnnotation"
        - $ref: "#/components/schemas/TextAnnotation"
      discriminator:
        propertyName: kind
      required:
        - kind
        - source
      example:
        kind: "TimeSeriesSegmentationAnnotation"
        source: "Human"
        segments:
          - 0.1
          - 0.3
          - 0.7
        annotations:
          - "click"
          - "click"
          - "rattle"

    AssetCorpusLink:
      type: object
      required:
        - uniqueName
        - assetName
        - corpusName
      description: >-
        Represents a link between an `Asset` and a `Corpus`.
        `assetName` and `corpusName` are not mandatory on upload.
      properties:
        uniqueName:
          type: string
          description: User-provided name that uniquely identifies this Asset in the target corpus.
        assetName:
          type: integer
          format: int64
        corpusName:
          type: integer
          format: int64

    AssignmentResponse:
      properties:
        response:
          $ref: "$components/schema/Annotation"
        notes:
          type: string

    AssignmentHistory:
      description: >-

        This object captures the ongoing work needed to complete an `Assignment`.

        The `response` field is required when moving from the `Created` to the `Annotated` state. It can also be given when moving from the `Annotated` state to the `Reviewed` state.


      required:
        - state
        - assignedToUser
        - dateEntered
      properties:
        annotation:
          $ref: '#/components/schemas/Annotation'
        notes:
          type: string
          description: "Free-form notes"
        state:
          description: >
            Created implies that the `Assignment` is waiting for `Assignment.annotatorId` to annotate it.

            `Annotated` implies that the `Assignment` is waiting for `Assignment.reviewerId` to review it.

            `Approved` or `Rejected` implies that the `Assignment` has been sent back to `Assignment.annotatorId` for further changes.

            `Superseded` implies that the underlying `Asset`s' content has been updated, meaning that the `Assignment` needs to be re-annotated by `Assignment.annotatorId`.

            `Deleted` implies that `currentUser` has removed the `Assignment` and that its results should no longer appear.
          type: string
          enum:
            - Created
            - Annotated
            - Approved
            - Rejected
            - Superseded
            - Deleted
        updatedByUser:
          description: >-
            Ignored on upload, records the application-global identifier of the user who generated this state change.
          type: integer
          format: int64
        assignedToUser:
          description: >-
            Records which user should progress this to the next state. If state is `Approved`, this can be blank.
          type: integer
          format: int64
        dateEntered:
          description: >-
            Ignored on upload, this records the UTC time that this update happened.
          type: string
          format: datetime

    Assignment:
      required:
        - question
        - created
        - assets
        - assignedAnnotatorId
      properties:
        assets:
          type: array
          items:
            type: integer
            format: int64
          description: "The Assets that will be displayed for this Assignment."
        annotatorId:
          type: integer
          format: int64
          description: "The user who will complete the question"
        question:
          $ref: "$/components/schemas/Question"
        reviewerId:
          type: integer
          format: int64
          description: >-
            Who will review this `Assignment`. If unset, or set to 0,
            the assignment will be automatically approved.
        created:
          type: string
          format: datetime

    BinaryAssetDescription:
      title: BinaryAsset
      type: object
      description: >-
        An `Asset` is an indivisable blob of data that can be annotated.
      required:
        - copyrightAndUsageRestrictions
        - checksum
        - mimeType
        - typeDescription
        - content
        - userIdWhoUploaded
        - dateUploaded
        - id
      properties:
        id:
          type: integer
          format: int64
          description: Ignored on upload.
        userIdWhoUploaded:
          type: integer
          format: int64
          description: Ignored on upload.
          default: 0
        content:
          type: string
          description: Base64-encoded byte array that makes up the `Asset`.
        metadata:
          type: object
          description: User-provided metadata to identify this object.
        dateUploaded:
          type: string
          format: dateTime
          description: When this asset was uploaded. Ignored on upload.
          default: now
        copyrightAndUsageRestrictions:
          type: string
          description: Contains user-provided information about Copyright, source, and redistribution.
        checksum:
          type: string
          format: base64
          description: Contains a SHA512 sum which verifies the binary content of this Asset.
        mimeType:
          type: string
          description: Detected mimetype for this object.
        typeDescription:
          type: string
          description: Hint for validation and display
          enum:
            - UTF8Text
            - Audio
            - Image
            - Video
            - Other

    BinaryAssetUpload:
      allOf:
        - $ref: "#/components/schemas/BinaryAssetDescription"
        - type: object
          properties:
            content:
              type: string
              description: Base64-encoded byte array that makes up the `Asset`.

    ConfigurationResponse:
      type: object
      description: >-
        Contains information about whether Annotatron needs further
        configuration to start working.
      required:
        - requiresSetup
      properties:
        requiresSetup:
          type: boolean
          description: >-
            If true, Annotatron needs additional setup steps.

    Corpus:
      title: Corpus
      type: object
      required:
        - name
        - dateCreated
      properties:
        name:
          type: string
          description: Unique name identifying this corpus
        description:
          type: string
          description: Human-readable description of what's in this corpus.
        created:
          type: string
          format: dateTime
          description: When this corpus was created.
        copyrightAndUsageRestrictions:
          type: string
          description: Human-readable copyright and usage restrictions.
      example:
        name: "VCTK"
        description: "Multi-speaker collection of short sentences."
        dateCreated: "2012-04-23T18:25:43.511Z"
        copyrightAndUsageRestrictions: >-
          This corpus is licensed under Open Data Commons Attribution License (ODC-By) v1.0.
            http://opendatacommons.org/licenses/by/1.0/
            http://opendatacommons.org/licenses/by/summary/

            http://homepages.inf.ed.ac.uk/jyamagis/page3/page58/page58.html

    DataLossReason:
      type: object
      properties:
        reason:
          type: string
          enum:
            - AssetStillLinkedToCorpus
            - AssetContainsAnnotationsInCorpus
            - QuestionHasAnnotations

    FieldError:
      type: object
      required:
        - name
        - error
        - warning
      properties:
        name:
          type: string
        error:
          type: string
        warning:
          type: boolean
          description: >-
            If true, then this validation message is a warning, meaning that it will be accepted by Annotatron if the present user is supposed to be reviewing this annotation. It's normally used to indicate policy violations, rather than integrity errors.

    GenericJSONAnnotation:
      allOf:
        - $ref: "#/components/schemas/AbstractAnnotation"
        - type: object
          required:
            - kind
            - content
          properties:
            content:
              type: object
              description: >-
                User-provided JSON content

    PasswordResetRequest:
      required:
        - newPassword
      properties:
        oldPassword:
          type: string
          description: The previously set password, if available.
        newPassword:
          type: string
          description: The password to set the user's account to.

    LoginRequest:
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string
          description: Plain-text password
      example:
        username: "admin"
        password: "S3CretPassw0rd"

    LoginResponse:
      required:
        - token
      properties:
        token:
          type: string
          description: >-
            This string must be used in all future HTTP transactions via the `Authorization: Bearer` HTTP header.
        passwordResetNeeded:
          type: boolean
          description: >-
            If true, the user must reset their password as soon as possible.

    MultipleChoiceQuestion:
      allOf:
        - $ref: "#/components/schemas/AbstractQuestion"
        - title: MultipleChoiceQuestion
          type: object
          required:
            - choices
            - kind
          properties:
            choices:
              description: >-
                Describes what the multiple choices are.
              type: array
              items:
                type: string
              example:
                - "Cat"
                - "Dog"
                - "Mongoose"

    NewUserRequest:
      required:
        - username
        - email
        - role
        - password
      properties:
        username:
          type: string
          description: "The name the `User` will use to login."
        email:
          type: string
          description: "Will be used to send notifications."
        password:
          type: string
        role:
          type: string
          enum:
            - Administrator
            - Staff
            - Annotator
            - Reviewer
          description: >-
            "Each role has fewer privileges than the one before."

    Question:
      oneOf:
        - $ref: "#/components/schemas/MultipleChoiceQuestion"
        - $ref: "#/components/schemas/TimeSeriesRangeQuestion"
        - $ref: "#/components/schemas/TimeSeriesSegmentationQuestion"
      discriminator:
        propertyName: kind

    # These are generic return/assignment types
    SuccessfulInsert:
      title: SuccesfulInsert
      type: object
      required:
        - insertedId
      properties:
        insertedId:
          type: integer
          format: int64
          example: 14
          description: An identifier which can later retrieve the inserted resource



    MultipleChoiceAnnotation:
      allOf:
        - $ref: "#/components/schemas/AbstractAnnotation"
        - type: object
          description: >-
            Annotation type which captures a `MultipleChoiceQuestion` output.
          required:
            - kind
            - choices
          properties:
            choices:
              type: array
              items:
                type: string

    TextAnnotation:
      allOf:
        - $ref: "#/components/schemas/AbstractAnnotation"
        - type: object
          description: >-
            Annotation type which contains a free-form text response
          required:
            - kind
            - content
          properties:
            content:
              type: string
              description: >-
                Free-form text input

    TimeSeriesRangeAnnotation:
      allOf:
        - $ref: "#/components/schemas/AbstractAnnotation"
        - type: object
          description: >-
            Captures the outcome of a `TimeSeriesRangeQuestion`
          required:
            - ranges
            - kind
          properties:
            ranges:
              type: array
              items:
                $ref: "#/components/schemas/TimeSeriesRangeTuple"
          example:
            ranges:
              - label: "Hello"
                start: 0.0
                end: 0.712
              - label: "World"
                start: 0.811
                end: 1.121

    TimeSeriesRangeQuestion:
      allOf:
        - $ref: "#/components/schemas/TimeSeriesSegmentationQuestion"
        - title: 1DRangeQuestion
          type: object
          required:
            - canOverlap
            - kind
          properties:
            canOverlap:
              description: >-
                If True, the user can create overlapping segments.
              type: boolean
              example: true

    TimeSeriesRangeTuple:
      type: object
      description: >-
        Used to demarcate start/end sections for a 1D audio file.
      required:
        - label
        - start
        - end
      properties:
        label:
          type: string
          example: "Hello"
        start:
          type: number
          example: 0.0
        end:
          type: number
          example: 0.7

    TimeSeriesSegmentationAnnotation:
      allOf:
        - $ref: "#/components/schemas/AbstractAnnotation"
        - type: object
          description: >-
            This object captures the outcome of a `TimeSeriesSegmentationQuestion`.
          required:
            - segments
            - annotations
            - kind
          properties:
            segments:
              description: >-
                Flat-list of timestamps.
              type: array
              items:
                type: number
              example:
                0.0
                0.712

            annotations:
              description: >-
                List of strings which contain the annotation information.
              type: array
              items:
                type: string
              example:
                - "Hello"
                - "World"

    TimeSeriesSegmentationQuestion:
      allOf:
        - $ref: "#/components/schemas/AbstractQuestion"
        - title: 1DSegmentationQuestion
          type: object
          required:
            - kind
          example:
            created: 2012-04-23T18:25:43.511Z
            summaryCode: WORDS
            humanPrompt: Divide this file into words
            kind: "TimeSeriesSegmentationQuestion"
            maximumSegments: 5
            minimumSegments: 2
            segmentChoices:
              - "hi"
              - "world"
            freeFormAllowed: true
            annotationInstructions: >-
              Click between each word.
            detailedAnnotationInstructions: >-
              * If word grouping is unclear, click around the unclear section and enter WORD1-...-WORDN in the freeform area.

          properties:
            maximumSegments:
              description: >-
                Describes the maximum number of segments that the `Annotator` is allowed to create. If unset, this is unrestricted.
              type: integer
              example: 5

            minimumSegments:
              description: >-
                Describes the minimum number of segments that the `Annotator` can create. If unset, this is zero.
              type: integer
              example: 0

            segmentChoices:
              description: >-
                If set, this field forces the user to further annotate the segments from the options in this field
              type: array
              items:
                type: string
              example:
                - "Cat"
                - "Dog"
                - "Mongoose"

            freeFormAllowed:
              description: >-
                If set to `true`, this field allows the user to specify
                a different response from that allowed by `segmentChoices`
              type: boolean
              example: true

    #
    # This section describes Authentication objects.
    #


    UserAssignments:
      required:
        - forReview
        - forAnnotation
      properties:
        forReview:
          type: array
          items:
            type: integer
            format: int64
        forAnnotation:
          type: array
          items:
            type: integer
            format: int64

    User:
      required:
        - username
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier
        username:
          type: string
          description: "The name that the `User` will use."
        created:
          type: string
          format: datetime
        role:
          type: string
          enum:
            - Administrator
            - Staff
            - Reviewer
            - Annotator


    ValidationError:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: "#/components/schemas/FieldError"
security:
  - bearerAuth: []