openapi: 3.0.3
info:
  title: qv - dlmw
  description: |-
    This is the documentation for the qv (Quadratic Voting) API.
  termsOfService: http://swagger.io/terms/
  contact:
    email: dylan@dlmw.ch
  license:
    name: GNU General Public License Version 3
    url: https://www.gnu.org/licenses/gpl-3.0.txt
  version: 0.0.1
externalDocs:
  description: Find out more about qv # todo
  url: http://swagger.io # todo
servers:
  - url: https://petstore3.swagger.io/api/v3 # todo
tags:
  - name: election
    description: Retrieve data related to elections

paths:
  /election:
    post:
      tags:
        - election
      summary: Create a new election
      operationId: createElection
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateElectionRequest"
      responses:
        201:
          description: Election created
        422:
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    Election:
      type: object
      required:
        - id
        - name
        - tokens
        - is_anonymous
        - expires_at
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        name:
          type: string
          minLength: 1
        tokens:
          type: integer
          minimum: 0
        is_anonymous:
          type: boolean
        max_voters:
          type: integer
          minimum: 1
          nullable: true
          description: Required when election is anonymous
        created_at:
          type: string
          format: date-time
          readOnly: true
        expires_at:
          type: string
          format: date-time
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        voters:
          type: array
          items:
            $ref: '#/components/schemas/Voter'

    Choice:
      type: object
      required:
        - text
        - election_id
      properties:
        text:
          type: string
          minLength: 1
        election_id:
          type: integer
          format: int64

    Voter:
      type: object
      required:
        - identity
        - election_id
      properties:
        identity:
          type: string
          minLength: 1
          description: When election is anonymous, passcodes will be pre-generated
        election_id:
          type: integer
          format: int64
        votes:
          type: array
          items:
            $ref: '#/components/schemas/Vote'

    Vote:
      type: object
      required:
        - voter_identity
        - election_id
      properties:
        voter_identity:
          type: string
          minLength: 1
        election_id:
          type: integer
          format: int64
        choice_text:
          type: string
          nullable: true
        tokens:
          type: integer
          minimum: 0
          nullable: true
        calculated_vote_count:
          type: integer
          readOnly: true
          description: Calculated as floor(sqrt(tokens))
        created_at:
          type: string
          format: date-time
          readOnly: true

    CreateElectionRequest:
      type: object
      required:
        - name
        - tokens
        - is_anonymous
        - expires_at
        - choices
      properties:
        name:
          type: string
          minLength: 1
        tokens:
          type: integer
          minimum: 0
        is_anonymous:
          type: boolean
        max_voters:
          type: integer
          minimum: 1
          nullable: true
          description: Required when election is anonymous
        expires_at:
          type: string
          format: date-time
        choices:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          uniqueItems: true

    ErrorResponse:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Human-readable error message
        code:
          type: integer
          description: Machine-readable error code
        details:
          type: object
          description: Additional error details when available
          nullable: true