openapi: "3.0.0"
info:
  version: 3.0.0
  title: Peregrine API documentation
servers:
  - url: http://edge.api.peregrine.ga:8080/
  - url: http://api.peregrine.ga:8080/
  - url: http://localhost:8080/
paths:
  /:
    get:
      summary: Get server uptime and health information
      operationId: health
      responses:
        "200":
          description: Server uptime and health information
          content:
            application/json:
              schema:
                required:
                  - startTime
                  - uptime
                  - listen
                  - services
                  - ok
                properties:
                  uptime:
                    description: Amount of time the server has been up
                    type: string
                    example: 9.614298073s
                  services:
                    description: Health of the services peregrine depends upon
                    required:
                      - tba
                      - postgresql
                    properties:
                      tba:
                        description: The Blue Alliance API health
                        type: boolean
                        example: true
                      postgresql:
                        description: PostgreSQL health
                        type: boolean
                        example: false
                  ok:
                    description: Health of peregrine and all of it's dependencies
                    type: boolean
                    example: false
  /authenticate:
    post:
      summary: Retrieve tokens for authorization
      operationid: authenticate
      tags:
        - authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: An alphanumeric string between 4 and 32 characters
                  example: franklin
                password:
                  type: string
                  description: A string between 8 and 128 characters
                  example: Q6qA6A22WLTO
      responses:
        "200":
          description: Successful authentication
          content:
            application/json:
              schema:
                required:
                  - refreshToken
                  - accessToken
                properties:
                  refreshToken:
                    $ref: "#/components/schemas/refreshToken"
                  accessToken:
                    $ref: "#/components/schemas/accessToken"
        "401":
          description: Failed to authenticate due to an incorrect username or password
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
        "422":
          description: Failed to validate username or password, or request body syntax was invalid
          content:
            text/plain:
              schema:
                type: string
                example: Unprocessable Entity
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /refresh:
    post:
      summary: Retrieve a new access token via a refresh token
      operationId: refresh
      tags:
        - authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - refreshToken
              properties:
                refreshToken:
                  $ref: "#/components/schemas/refreshToken"
      responses:
        "200":
          description: Sucessfully generated a new access token
          content:
            application/json:
              schema:
                required:
                  - accessToken
                properties:
                  accessToken:
                    $ref: "#/components/schemas/accessToken"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "422":
          description: Request body syntax was invalid
          content:
            text/plain:
              schema:
                type: string
                example: Unprocessable Entity
        "500":
          $ref: "#/components/responses/internalServerError"
  /users:
    post:
      summary: Create a new user
      description:
        Note that if you specify roles higher than your own roles they will be reset.
        For example, you can't create a verified user in another realm if you're not
        a global admin, and you can't create an admin if you're not an admin.
      operationId: createUser
      security:
        - BearerAuth: []
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/user"
      responses:
        "201":
          description: Successfully created user
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "409":
          $ref: "#/components/responses/conflictError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
    get:
      summary: Get all visible users
      description:
        Note that only admins can get users. Global admins can get all users, and realm
        admins can get all users in their realm.
      operationId: getUsers
      security:
        - BearerAuth: []
      tags:
        - users
      responses:
        "200":
          description: Successfully fetched users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/user"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /users/{id}:
    parameters:
      - in: path
        name: id
        schema:
          $ref: "#/components/schemas/id"
        required: true
        description: Numeric User ID
    get:
      summary: Get a user
      operationId: getUser
      security:
        - BearerAuth: []
      tags:
        - users
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/user"
        "400":
          $ref: "#/components/responses/badRequestError"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
    patch:
      summary: Update all or parts of a user
      description:
        Any null or undefined fields will not be updated. Global admins can patch any user,
        realm admins can patch users in their realm, and any user can patch themselves.
      operationId: patchUser
      security:
        - BearerAuth: []
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/user"
      responses:
        "204":
          description: Successfully patched user
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
    delete:
      summary: Delete a user
      operationId: deleteUser
      security:
        - BearerAuth: []
      tags:
        - users
      responses:
        "204":
          description: Successfully deleted user
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /schemas:
    get:
      summary: Get all visible schemas
      description:
        Note that this endpoint will return all schemas if you're a global admin, realm and public schemas
        if you're authenticated, and just public schemas if you're not authenticated.
      operationId: getSchemas
      tags:
        - schemas
      security:
        - BearerAuth: []
      parameters:
        - in: query
          name: year
          schema:
            type: integer
            example: 2018
          required: false
          description: Get schemas for a specified year
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/schema"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "500":
          $ref: "#/components/responses/internalServerError"
    post:
      summary: Create a new schema
      description:
        Note that only global admins can create a schema for a year. Realm admins can only create a schema
        for their realm. Normal users cannot create schemas. Also note if an ID is included on the schema
        it will be ignored.
      operationId: createSchema
      security:
        - BearerAuth: []
      tags:
        - schemas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/schema"
      responses:
        "201":
          description: Successfully created schema
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "409":
          $ref: "#/components/responses/conflictError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /schemas/{id}:
    parameters:
      - in: path
        name: id
        schema:
          $ref: "#/components/schemas/id"
        required: true
        description: Numeric Schema ID
    get:
      summary: Get a schema by ID
      operationId: getSchema
      security:
        - BearerAuth: []
      tags:
        - schemas
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/schema"
        "400":
          $ref: "#/components/responses/badRequestError"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events:
    get:
      summary: Get all visible events
      operationId: getEvents
      security:
        - BearerAuth: []
      tags:
        - events
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/event"
        "400":
          $ref: "#/components/responses/badRequestError"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}:
    parameters:
      - $ref: "#/components/parameters/eventKey"
    get:
      summary: Get a specific event
      operationId: getEvent
      security:
        - BearerAuth: []
      tags:
        - events
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/event"
        "400":
          $ref: "#/components/responses/badRequestError"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
    put:
      summary: Create a new custom event (not on TBA)
      operationId: putEvent
      description:
        This endpoint allows realm admins and global admins to create custom events. This can
        be useful if an offseason event isn't on The Blue Alliance and you still want to scout
        it.
      tags:
        - events
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/event"
      responses:
        "201":
          description: Successfully created event
        "204":
          description: Successfully replaced existing event
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/stats:
    parameters:
      - $ref: "#/components/parameters/eventKey"
    get:
      summary: Get stats summary for all teams at an event
      operationId: getEventStats
      tags:
        - stats
      security:
        - BearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  required:
                    - team
                    - summary
                  properties:
                    team:
                      type: string
                      example: frc2733
                    summary:
                      $ref: "#/components/schemas/stats"
        "400":
          $ref: "#/components/responses/badRequestError"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/matches/{matchKey}/teams/{teamKey}/stats:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - $ref: "#/components/parameters/matchKey"
      - $ref: "#/components/parameters/teamKey"
    get:
      summary: Get stats summary for team in specific match
      operationId: getMatchTeamStats
      tags:
        - stats
      security:
        - BearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                required:
                  - team
                  - summary
                properties:
                  team:
                    type: string
                    example: frc2733
                  summary:
                    $ref: "#/components/schemas/stats"
        "400":
          $ref: "#/components/responses/badRequestError"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/matches:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - in: query
        name: team
        schema:
          type: array
          items:
            $ref: "#/components/schemas/teamKey"
        description: Filter matches with specified teams. Supports multiple teams.
        style: form
        explode: true
    get:
      summary: Get all matches for an event
      operationId: getMatches
      security:
        - BearerAuth: []
      tags:
        - matches
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/match"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "500":
          $ref: "#/components/responses/internalServerError"
    post:
      summary: Create a new match for an event
      operationId: createMatch
      description:
        Note that global admins can create matches on any event, and realm admins
        can create matches on events in their realm. Normal users cannot create
        matches.
      tags:
        - matches
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/match"
      responses:
        "201":
          description: Successfully created event
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/matches/{matchKey}:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - $ref: "#/components/parameters/matchKey"
    get:
      summary: Get a match
      description:
        Note that you can only get matches for events you have access to. A global admin
        can get matches for any event, otherwise you can only get matches for public events
        and events in your realm.
      security:
        - BearerAuth: []
      operationId: getMatch
      tags:
        - matches
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/match"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/teams:
    parameters:
      - $ref: "#/components/parameters/eventKey"
    get:
      summary: Get ranking information for all teams at an event
      operationId: getEventTeams
      tags:
        - teams
      security:
        - BearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/eventTeam"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/teams/{teamKey}:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - $ref: "#/components/parameters/teamKey"
    get:
      summary: Get ranking information about a team at an event
      operationId: getTeamRankingData
      security:
        - BearerAuth: []
      tags:
        - teams
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/eventTeam"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/teams/{teamKey}/comments:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - $ref: "#/components/parameters/teamKey"
    get:
      summary: Get comments about a team at an event
      operationId: getTeamEventComments
      security:
        - BearerAuth: []
      tags:
        - comments
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/comment"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/matches/{matchKey}/reports/{teamKey}:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - $ref: "#/components/parameters/matchKey"
      - $ref: "#/components/parameters/teamKey"
    get:
      summary: Get reports for a team in a match at an event
      operationId: getTeamMatchReports
      security:
        - BearerAuth: []
      tags:
        - reports
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/report"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
    put:
      summary: Submit a report for a team in a match at an event
      security:
        - BearerAuth: []
      operationId: postTeamMatchReport
      tags:
        - reports
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/report"
      responses:
        "201":
          description: Submitted new report
        "204":
          description: Successfully replaced existing report
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /events/{eventKey}/matches/{matchKey}/comments/{teamKey}:
    parameters:
      - $ref: "#/components/parameters/eventKey"
      - $ref: "#/components/parameters/matchKey"
      - $ref: "#/components/parameters/teamKey"
    get:
      summary: Get comments for a team in a match at an event
      operationId: getTeamMatchComments
      security:
        - BearerAuth: []
      tags:
        - comments
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/comment"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
    put:
      summary: Submit a comment for a team in a match at an event
      security:
        - BearerAuth: []
      operationId: postTeamMatchComment
      tags:
        - comments
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/comment"
      responses:
        "201":
          description: Submitted new comment
        "204":
          description: Successfully replaced existing comment
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /teams/{teamKey}:
    parameters:
      - $ref: "#/components/parameters/teamKey"
    get:
      summary: Get general info for a specific team
      operationId: getTeam
      tags:
        - teams
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/team"
        "404":
          $ref: "#/components/responses/notFoundError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /leaderboard:
    get:
      summary: Get a count of reports submitted for each reporter
      operationId: getLeaderboard
      tags:
        - leaderboard
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    reporterId:
                      type: integer
                      example: 4 # josiah
                    reports:
                      type: integer
                      example: 9001
        "500":
          $ref: "#/components/responses/internalServerError"
  /realms:
    get:
      summary: Get all realms
      operationId: getRealms
      security:
        - BearerAuth: []
      tags:
        - realms
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/realm"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "500":
          $ref: "#/components/responses/internalServerError"
    post:
      summary: Create a new realm
      description: Only global admins can create realms.
      operationId: createRealm
      tags:
        - realms
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/realm"
      responses:
        "201":
          description: Successfully created realm
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/realm"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "409":
          $ref: "#/components/responses/conflictError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
  /realms/{id}:
    get:
      summary: Get a realm by ID
      operationId: getRealm
      security:
        - BearerAuth: []
      tags:
        - realms
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/realm"
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "409":
          $ref: "#/components/responses/conflictError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
    post:
      summary: Update a realm
      description: Global admins can update any realm. Realm admins can update their realm.
      operationId: updateRealm
      tags:
        - realms
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/realm"
      responses:
        "204":
          description: Successfully updated realm
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "404":
          $ref: "#/components/responses/notFoundError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
    delete:
      summary: Delete a realm
      operationId: deleteRealm
      security:
        - BearerAuth: []
      tags:
        - realms
      responses:
        "204":
          description: Successfully deleted realm
        "401":
          $ref: "#/components/responses/unauthorizedError"
        "403":
          $ref: "#/components/responses/forbiddenError"
        "409":
          $ref: "#/components/responses/conflictError"
        "422":
          $ref: "#/components/responses/unprocessableEntityError"
        "500":
          $ref: "#/components/responses/internalServerError"
components:
  parameters:
    teamKey:
      in: path
      name: teamKey
      schema:
        $ref: "#/components/schemas/teamKey"
      required: true
      description: Team Key
    eventKey:
      in: path
      name: eventKey
      schema:
        $ref: "#/components/schemas/eventKey"
      required: true
      description: Event Key
    matchKey:
      in: path
      name: matchKey
      schema:
        $ref: "#/components/schemas/matchKey"
      required: true
      description: Match Key
  responses:
    internalServerError:
      description: Failed due to an internal server error
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/internalServerError"
    unauthorizedError:
      description: Invalid access token, please obtain a new access token
      content:
        text/plain:
          schema:
            type: string
            example: Unauthorized
    forbiddenError:
      description: Your access token is valid, but you lack the roles to perform this operation
      content:
        text/plain:
          schema:
            type: string
            example: Forbidden
    notFoundError:
      description: Unable to find that resource
      content:
        text/plain:
          schema:
            type: string
            example: Not Found
    unprocessableEntityError:
      description: Request body syntax was invalid
      content:
        text/plain:
          schema:
            type: string
            example: Unprocessable Entity
    conflictError:
      description: A resource with a similar unique key exists (e.g. username or id)
      content:
        text/plain:
          type: string
          example: Conflict
    badRequestError:
      description: Your request was invalid
      content:
        text/plain:
          type: string
          example: Bad Request
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    teamKey:
      type: string
      example: frc2733
    eventKey:
      type: string
      example: 2018pncmp
    matchKey:
      type: string
      example: qm30
    realm:
      required:
        - name
        - shareReports
        - id
      properties:
        name:
          type: string
          example: Pigmice
        shareReports:
          type: boolean
          example: true
        id:
          $ref: "#/components/schemas/id"
    reportStat:
      required:
        - name
        - value
      properties:
        name:
          type: string
          example: Sandstorm 2
        value:
          type: number
          example: 2
    report:
      required:
        - data
      properties:
        reporterId:
          $ref: "#/components/schemas/id"
        data:
          $ref: "#/components/schemas/reportData"
    comment:
      required:
        - comment
        - matchKey
      properties:
        id:
          $ref: "#/components/schemas/id"
        reporterId:
          $ref: "#/components/schemas/id"
        comment:
          type: string
          example: "Played good defense"
        matchKey:
          $ref: "#/components/schemas/matchKey"
    reportData:
      type: array
      items:
        $ref: "#/components/schemas/reportStat"
    match:
      required:
        - key
        - redAlliance
        - blueAlliance
      properties:
        key:
          $ref: "#/components/schemas/matchKey"
        time:
          type: string
          format: date-time
          example: "2018-04-06T23:21:38Z"
        scheduledTime:
          type: string
          format: date-time
          example: "2018-04-06T23:18:00Z"
        redScore:
          type: integer
          example: 426
        blueScore:
          type: integer
          example: 265
        redAlliance:
          type: array
          items:
            type: string
            example: frc5468
        blueAlliance:
          type: array
          items:
            type: string
            example: frc4488
    stats:
      type: array
      items:
        description: A list of stat max/avgs
        required:
          - max
          - avg
          - name
        properties:
          max:
            type: number
            format: double
            example: 4
          avg:
            type: number
            format: double
            example: 2.25
          name:
            type: string
            example: Rocket Hatches Lvl 1
    event:
      required:
        - key
        - name
        - startDate
        - endDate
        - webcasts
        - locationName
        - lat
        - lon
      properties:
        key:
          $ref: "#/components/schemas/eventKey"
        realmId:
          $ref: "#/components/schemas/id"
        schemaId:
          $ref: "#/components/schemas/id"
        name:
          type: string
          example: Gibraltar
        district:
          type: string
          example: fim
        fullDistrict:
          type: string
          example: FIRST In Michigan
        week:
          type: integer
          example: 4
        startDate:
          type: string
          format: date-time
          example: "2019-02-28T05:00:00Z"
        endDate:
          type: string
          format: date-time
          example: "2019-03-02T05:00:00Z"
        webcasts:
          type: array
          items:
            type: string
            example: https://www.twitch.tv/firstinspires
        locationName:
          type: string
          example: UW-Milwaukee Panther Arena
        lat:
          type: number
          format: double
          example: 43.0417381
        lon:
          type: number
          format: double
          example: -87.9168724
    eventTeam:
      required:
        - team
      properties:
        team:
          type: string
          example: frc2733
        rank:
          type: integer
          format: int32
          example: 12
        rankingScore:
          type: number
          format: double
          example: 3.6
    team:
      required:
        - key
      properties:
        key:
          type: string
          example: frc2733
        nickname:
          type: string
          example: RAGE Robotics ⚙️
    id:
      description: Auto-increment 64-bit integer that identifies a resource
      type: integer
      format: int64
      example: 1
      readOnly: true
    schema:
      required:
        - id
        - schema
      properties:
        id:
          $ref: "#/components/schemas/id"
        year:
          type: integer
          format: int64
          example: 2018
        realmId:
          $ref: "#/components/schemas/id"
        schema:
          $ref: "#/components/schemas/statDescriptions"
    statDescriptions:
      type: array
      items:
        required:
          - name
        properties:
          name:
            type: string
            example: Cargo Placed
          reportReference:
            type: string
            example: Cargo Placed
          tbaReference:
            type: string
            example: endgameRobot{{.RobotPosition}}
          anyOf:
            $ref: "#/components/schemas/anyOf"
          sum:
            $ref: "#/components/schemas/sum"
          hide:
            type: boolean
            example: true
          period:
            type: string
            example: auto
          type:
            type: string
            enum: [number, boolean, string]
    anyOf:
      type: array
      items:
        properties:
          name:
            type: string
            example: endgame
          equals:
            type: string
            example: HabLevel1
        required:
          - name
          - equals
    sum:
      type: array
      items:
        properties:
          name:
            type: string
            example: endgame
        required:
          - name
    user:
      required:
        - id
        - username
        - password
        - realmId
        - firstName
        - lastName
      properties:
        id:
          $ref: "#/components/schemas/id"
        username:
          type: string
          example: franklin
        password:
          type: string
          example: Sxam0dO3aMQW
          writeOnly: true
        realmId:
          $ref: "#/components/schemas/id"
        firstName:
          type: string
          example: Franklin
        lastName:
          type: string
          example: Harding
        stars:
          $ref: "#/components/schemas/stars"
        roles:
          $ref: "#/components/schemas/roles"
    stars:
      type: array
      items:
        type: string
        example: 2018pncmp
    roles:
      required:
        - isSuperAdmin
        - isAdmin
        - isVerified
      properties:
        isSuperAdmin:
          type: boolean
          example: true
        isAdmin:
          type: boolean
          example: true
        isVerified:
          type: boolean
          example: false
    accessToken:
      type: string
      description: Short lived (1 day) JWT for API authorization
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwZXJlZ3JpbmVSb2xlcyI6eyJpc1N1cGVyQWRtaW4iOnRydWUsImlzQWRtaW4iOnRydWUsImlzVmVyaWZpZWQiOnRydWV9LCJwZXJlZ3JpbmVSZWFsbSI6MSwiZXhwIjoxNTQ3NjcyNDE2LCJzdWIiOiIxIn0.FMsGteZSZ53YmBFAKFHTde_vTymvuT0iFfLGPmcbkDQ
    refreshToken:
      type: string
      description: Long lived (4 week) JWT for generating new access tokens without re-authenticating
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwZXJlZ3JpbmVQYXNzd29yZENoYW5nZWQiOiIyMDE5LTAxLTA5VDIyOjUxOjMxWiIsImV4cCI6MTU1MDAwNTIxNiwic3ViIjoiMSJ9.cCnaInxuIdrkZLTkVpx4i9iALoUzQTIYKWc5OtTroiM
    internalServerError:
      type: string
      example: Internal Server Error
    ValidationError:
      required:
        - error
      properties:
        error:
          type: string
          example: "Key: 'baseUser.Password' Error:Field validation for 'Password' failed on the 'gte' tag"