definitions.yaml

---

definitions:
  User:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - type: object
        description: User
        required:
          - name
          - username
        properties:
          name:
            type: string
            description: >-
              This is basically the display-name of the user on the platform. It
              returns the username if it is defined, common_name otherwise.
            default: John
          username:
            type: string
            description: An unique alias of the user. The default value is an empty string.
            default: John
          common_name:
            type: string
            description: The real name of the user. Required.
          about_me:
            type: string
            description: |
              A short text where the user describes himself. The default value
              is null.
            default: "I'm the choosen one"
          gamification:
            $ref: '#/definitions/Gamification'
          total_posts:
            type: integer
            description: Total number of posts made by user
          profile_images:
            $ref: '#/definitions/ProfileImages'
          wallpapers:
            $ref: '#/definitions/Wallpapers'
          created_at:
            type: string
            description: 'The date and time when the user was created, in ISO 8601 format.'
          updated_at:
            type: string
            description: |
              The date and time when the user data was last updated, in ISO 8601
              format. If the user data was never updated, the value is identical
              to created_at.
          url:
            type: string
            description: |
              The full URL of the user page. Per default it is
              https://your.domain/users/name where "name" is the URL-encoded
              name.
  UsersResponse:
    type: object
    required:
      - total_count
      - list
    properties:
      total_count:
        type: integer
        minimum: 0
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/User'
  UserStatistic:
    type: object
    description: "Overview of user's activity"
    required:
      - feedbacks
      - answers
      - votes
    properties:
      feedbacks:
        type: object
        required:
          - total_count
          - list
        properties:
          total_count:
            description: Total number of feedbacks that user left
            type: integer
          list:
            type: array
            items:
              $ref: '#/definitions/Topic'
      answers:
        type: object
        required:
          - total_count
          - list
        properties:
          total_count:
            description: Total number of feedbacks that user left
            type: integer
          list:
            type: array
            items:
              $ref: '#/definitions/Answer'
      votes:
        type: object
        required:
          - total_count
          - list
        properties:
          total_count:
            description: Total number of feedbacks that user left
            type: integer
          list:
            type: array
            items:
              $ref: '#/definitions/Vote'
  Gamification:
    type: object
    description: An object containing the gamification details of the user
    required:
      - level
      - score
    properties:
      level:
        type: integer
        description: >-
          An integer representing the current experience level of the user based
          on his score.
        minimum: 0
        maximum: 5
      score:
        type: number
        description: >-
          The sum of all points gathered through different actions like posting
          a new topic or receiving a vote on ones answer. Different actions
          yield different (configurable) amounts of points.
        minimum: 0
        maximum: 5
  WidgetContainer:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithUUID'
      - type: object
        required:
          - name
          - url
          - feedbacks
          - statistic
        properties:
          feedbacks:
            type: array
            items:
              $ref: '#/definitions/Topic'
          name:
            type: string
            description: Name of the item been reviewed
          url:
            type: string
            description: Page where the container (website) can be found
          statistic:
            type: object
            properties:
              '1':
                description: Number of feedbacks with rating of 1
                type: integer
                minimum: 0
              '2':
                description: Number of feedbacks with rating of 2
                type: integer
                minimum: 0
              '3':
                description: Number of feedbacks with rating of 3
                type: integer
                minimum: 0
              '4':
                description: Number of feedbacks with rating of 4
                type: integer
                minimum: 0
              '5':
                description: Number of feedbacks with rating of 5
                type: integer
                minimum: 0
  BaseTopic:
    type: object
    required:
      - body
      - author
      - status
    properties:
      body:
        type: string
        description: >-
          The body text of the topic. It may contain some basic HTML, restricted
          to the following tags: p, br, blockquote, ol, ul, li, a (including
          attributes href, title, target), em, i, strong, b.
        default: >-
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent nec
          purus dui. Nulla quis lectus iaculis, porttitor est sit amet, cursus
          lectus. Aenean ac tortor vel arcu rutrum blandit
      author:
        $ref: '#/definitions/User'
      status:
        type: string
        description: Status of the Feedback
        default: fresh
        enum:
          - fresh
          - discussed
          - answered
          - closed
          - faq
  Topic:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/BaseTopic'
      - $ref: '#/definitions/ModelWithPageObject'
  Feedback:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/BaseTopic'
      - $ref: '#/definitions/ModelWithPageObject'
      - type: object
        required:
          - title
          - rating
        properties:
          type:
            type: string
            description: |
              The content type of the topic. Possible values are Question,
              Feedback, Tutorial, Article, and Faq.
          title:
            type: string
            description: The title text of the topic.
          rating:
            type: integer
            description: |
              This attribute is not related to Rating. The attribute is only
              relevant for topics of the type Feedback. The number represents
              the author\'s rating of the issue he is giving feedback for. Higher
              numbers mean better rating. Per default, numbers from 1 to 5 are
              supported and displayed in the form of smileys. The default value
              is 5.
  Question:
    allOf:
      - $ref: '#/definitions/BaseTopic'
      - $ref: '#/definitions/ModelWithPageObject'
      - type: object
        required:
          - title
        properties:
          title:
            type: string
            description: The title text of the topic.
  Answer:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/ModelWithPageObject'
      - type: object
        required:
          - body
          - author
          - private
          - mood
        properties:
          body:
            type: string
            description: >-
              The body text of the answer. It may contain some basic HTML,
              restricted to the following tags: p, br, blockquote, ol, ul, li, a
              (including attributes href, title, target), em, i, strong, b.
            default: Shall I compare thee to a summer’s day?
          author:
            $ref: '#/definitions/User'
          answerable_id:
            type: integer
            minimum: 1
            description: The unique identifier of the answered item.
          answerable_type:
            type: string
            description: The type of the answered item. Currently limited to Topic.
            default: Feedback
          private:
            type: boolean
            description: >-
              The answer will only be accessible to agents and the user who
              posted it
            default: false
          solution:
            type: boolean
            description: >-
              True, if the answer is the accepted solution to the question. Only
              applicable if the answerable_type is a topic of the type Question
            default: false
          mood:
            type: integer
            minimum: 0
            maximum: 5
            description: >-
              A number representing the mood of the answering user. Higher
              numbers mean better mood. Per default, numbers from 1 to 4 are
              supported and presented in the form of smileys.
          rating:
            type: integer
            minimum: 0
            description: 'Deprecated, will be removed.'
          recent_report_id:
            type: integer
            minimum: 1
            description: >-
              The unique identifier of the last report filed by users about the
              current answer. Will only be accessible to team members. The
              default value is null.
          attachments:
            type: array
            description: An array of IDs of Assets. The default value is an empty array.
            items:
              $ref: '#/definitions/Assets'
          statistics:
            $ref: '#/definitions/Statistic'
  Producttest:
    description: >
      Product Test may be in the one of free phases: introduction, testing,
      final
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - type: object
        required:
          - name
          - description
          - phase
          - application_description
          - test_description
          - summary
          - application_introduction
          - application_closing_text
          - test_introduction
          - test_closing_text
          - invite_text
          - decline_text
          - conditions
          - application_runtime
          - participations_limit
          - test_limit
          - is_teaser
          - draft
          - featured_images
          - products
          - opened_at
          - starts_at
          - test_runtime
          - closed_at
          - statictics
          - participation_requests
          - reviews
          - actions
        properties:
          name:
            type: string
            description: Name of the product test
          description:
            type: string
            description: General description
          phase:
            type: string
            description: Name of the current phase for this product test
            enum:
              - introduction
              - testing
              - final
          application_description:
            type: string
            description: Application description
          test_description:
            type: string
            description: Description of the product test
          summary:
            type: string
            description: Introduction text for active or completed test
          application_introduction:
            type: string
            description: Introduction text on application form
          application_closing_text:
            type: string
            description: Closing text below application form
          test_introduction:
            type: string
            description: Introduction text
          test_closing_text:
            type: string
            description: The conclusion of the text
          invite_text:
            type: string
            description: Text for invite mail
          decline_text:
            type: string
            description: Text for decline mail
          conditions:
            type: string
            description: Terms and Conditions
          application_runtime:
            type: integer
            description: Runtime of application phase in days
          participations_limit:
            type: integer
            description: Number of users who can participate
          test_limit:
            type: integer
            description: Maximum number of the test reviews
          is_teaser:
            type: boolean
            description: If this product test is teaser for the client
          draft:
            type: boolean
            description: Draft flag
          products:
            type: array
            description: List of products included into this product test
            items:
              $ref: '#/definitions/Product'
          featured_images:
            type: array
            description: Images
            items:
              $ref: '#/definitions/Asset'
          opened_at:
            type: string
            format: date-time
            description: Timestamp of application start
          starts_at:
            type: string
            format: date-time
            description: Timestamp of tests start
          test_runtime:
            type: integer
            description: Runtime of test phase in days
          closed_at:
            type: string
            format: date-time
            description: Date when test phase finishing
          statictics:
            $ref: '#/definitions/Statistic'
          participation_requests:
            description: Available only during the period of the "Introduction Phase"
            type: array
            items:
              $ref: '#/definitions/ParticipationRequest'
          reviews:
            description: Available only during the period of "Final Phase"
            type: array
            items:
              $ref: '#/definitions/Review'
          actions:
            type: array
            items:
              type: string
              enum:
                - participate
                - review
  ParticipationRequest:
    allOf:
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/ModelWithTimestamps'
      - type: object
        required:
          - user
          - status
          - field_values
          - statistics
        properties:
          user:
            $ref: '#/definitions/User'
          status:
            type: string
            description: |
              Status of the request.
              Available statuses: `new invited pending confirmed auto_confirmed`
          field_values:
            type: array
            items:
              $ref: '#/definitions/FieldValue'
          statistics:
            type: object
            properties:
              answers_count:
                type: integer
              vote_count:
                type: integer
  Field:
    type: object
    required:
      - id
      - name
      - type
      - is_mandatory
    properties:
      id:
        type: integer
      name:
        type: string
        description: Name of this field
      type:
        type: string
        description: Internal type of the field
      is_mandatory:
        type: boolean
        description: Mandatory or optional flag
  FieldValue:
    type: object
    required:
      - id
      - field
      - value
    properties:
      id:
        type: integer
      field:
        $ref: '#/definitions/Field'
      value:
        type: string
        description: Value of this field
  ParticipationRequestsResponse:
    type: object
    required:
      - total_count
      - list
    properties:
      total_count:
        type: integer
        minimum: 0
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/ParticipationRequest'
  ParticipationRequestsStructureResponse:
    type: object
    properties:
      list:
        type: array
        minItems: 1
        items:
          $ref: '#definitions/Field'
  Review:
    allOf:
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/ModelWithTimestamps'
      - type: object
        required:
          - user
          - language
          - criteria_values
          - title
          - body
          - average_rating
          - statistics
        properties:
          user:
            $ref: '#/definitions/User'
          language:
            $ref: '#/definitions/Language'
          title:
            type: string
            description: /?\ is it used?
          body:
            type: string
            description: /?\ is it used?
          criteria_values:
            type: array
            items:
              $ref: '#/definitions/FieldValue'
          average_rating:
            type: number
            description: Average rating given by user
          statistics:
            type: object
            properties:
              answers_count:
                type: integer
              vote_count:
                type: integer
  ReviewStructure:
    type: object
    properties:
      list:
        type: array
        minItems: 1
        items:
          $ref: '#definitions/Field'
  Language:
    type: object
  ReviewsResponse:
    type: object
    required:
      - total_count
      - list
    properties:
      total_count:
        type: integer
        minimum: 0
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/Review'
  Product:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - type: object
        required:
          - external_id
          - name
          - description
          - price
          - url
        properties:
          external_id:
            type: string
            description: ID of the product in external system
          name:
            type: string
            description: Name of the product
          description:
            type: string
            description: 'Additional text, description of the product'
          price:
            type: number
            description: Price of the product
          url:
            type: string
            description: URL of the page with the product
  TopicsResponse:
    type: object
    required:
      - total_count
      - list
    properties:
      total_count:
        type: integer
        minimum: 0
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/Topic'
  FeedbacksResponse:
    type: object
    required:
      - total_count
      - list
      - current_user_feedback
    properties:
      total_count:
        type: integer
        minimum: 0
      current_user_feedback:
        $ref: '#/definitions/Topic'
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/Topic'
  QuestionsResponse:
    type: object
    required:
      - total_count
      - list
    properties:
      total_count:
        type: integer
        minimum: 0
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/Question'
  AnswersResponse:
    type: object
    required:
      - total_count
      - list
    properties:
      total_count:
        type: integer
        minimum: 0
      list:
        type: array
        minItems: 0
        items:
          $ref: '#/definitions/Answer'
  AssetVariant:
    type: object
    required:
      - width
      - height
      - url
    properties:
      width:
        type: integer
        minimum: 10
        maximum: 400
        description: An Integer representing the asset variant width in pixels
      height:
        type: integer
        minimum: 10
        maximum: 400
        description: An Integer representing the asset variant height in pixels
      url:
        type: string
        description: >-
          A String representing the file path, relative to the site root (i.e.
          starting with a slash).
  Asset:
    allOf:
      - $ref: '#/definitions/ModelWithTimestamps'
      - $ref: '#/definitions/ModelWithID'
      - type: object
        required:
          - type
          - title
          - variants
          - file
          - url
        properties:
          type:
            type: string
            description: >-
              The type of the asset. Possible values are Image, Document, and
              Link.
            default: Image
          title:
            type: string
            description: The title text of the asset
            default: ''
          description:
            type: string
            description: The description text of the asset
            default: ''
          url:
            type: string
            description: URL of the original file
          uploader:
            $ref: '#/definitions/User'
          variants:
            properties:
              small:
                $ref: '#/definitions/AssetVariant'
              medium:
                $ref: '#/definitions/AssetVariant'
              large:
                $ref: '#/definitions/AssetVariant'
          file:
            type: string
            description: >-
              The path of the file, relative to the site root (i.e. starting
              with a slash).
  Assets:
    type: array
    description: >-
      An asset is an image, a document, or a link and can be attached to a
      topic, an answer and other objects. An asset object does not contain
      binary data, but references them by URL.
    items:
      $ref: '#/definitions/Asset'
  ProfileImages:
    type: array
    description: >-
      An array of image assets that are displayed as profile images. The default
      value is an empty array.
    items:
      $ref: '#/definitions/Asset'
  Wallpapers:
    type: array
    description: >-
      An array of image assets that are displayed as background image. The
      default value is an empty array.
    items:
      $ref: '#/definitions/Asset'
  Statistic:
    type: object
    properties:
      vote_count:
        type: number
        description: to be done
        default: 0
  Vote:
    allOf:
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/ModelWithTimestamps'
      - type: object
        required:
          - votable_type
          - votable_id
          - votable
          - user
        properties:
          votable_type:
            type: string
            description: Name of the object that was voted
          votable_id:
            type: integer
            description: id of the object that was voted
          votable:
            $ref: '#/definitions/Topic'
          user:
            $ref: '#/definitions/User'
  Report:
    allOf:
      - $ref: '#/definitions/ModelWithID'
      - $ref: '#/definitions/ModelWithTimestamps'
  Votes:
    type: array
    items:
      $ref: '#/definitions/Vote'
  ModelWithTimestamps:
    type: object
    required:
      - created_at
      - updated_at
    properties:
      created_at:
        type: string
        format: date-time
        description: 'The date and time when the answer was posted, in ISO 8601 format.'
      updated_at:
        type: string
        format: date-time
        description: >-
          The date and time when the answer was last updated, in ISO 8601
          format. If the answer was never updated, the value is identical to
          created_at.
  ModelWithID:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        description: The unique identifier
        minimum: 1
        maximum: 999999
  ModelWithUUID:
    type: object
    required:
      - uuid
    properties:
      uuid:
        type: string
        description: The unique identifier
        format: uuid
  ModelWithPageObject:
    type: object
    required:
      - page_object
    properties:
      page_object:
        type: object
        required:
          - url
          - title
        properties:
          url:
            type: string
            description: URL where the page with the content can be found
          title:
            type: string
            description: Title of the page/product
  WidgetContainerStatisticResponse:
    type: object
    required:
      - average
      - '5'
      - '4'
      - '3'
      - '2'
      - '1'
    properties:
      '1':
        type: integer
        description: Number of feedbacks with grade 1
      '2':
        type: integer
        description: Number of feedbacks with grade 2
      '3':
        type: integer
        description: Number of feedbacks with grade 3
      '4':
        type: integer
        description: Number of feedbacks with grade 4
      '5':
        type: integer
        description: Number of feedbacks with grade 5
      average:
        type: number
        description: Average rating of the WidgetContainer