openapi: 3.0.3
info:
  title: User API - V1
  version: 1.3.0
  description: API for user login and registration via social platforms.
#    _Changelog_
#    - **1.4.0**
#      - `account` endpoints
#    - **1.3.0**
#      - Introduced practice for `*Rules` endpoints
#    - **1.2.0**
#      - Add `Password` endpoints
#    - **1.1.0**
#      - Add `OAuth` endpoints
#    - **1.0.0**
#      - Initial API version
#      - `auth` endpoints
servers:
  - url: https://api-staging.sharin.app
    description: Staging server (pre-production)
  - url: https://api.sharin.app
    description: Production server
  - url: http://api.sharinapp.local
    description: Local development server (used in tests)

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key required for all calls
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Bearer token authentication. Provide the access token in the Authorization header as: Bearer {token}"

  parameters:
    VerificationToken:
        name: token
        in: query
        required: true
        description: Verification token generated by the local system
        schema:
          type: string
  schemas:
    SuccessResponse:
      type: object
      required: [meta, data]
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/User'
        meta:
          allOf:
            - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
    User:
      type: object
      properties:
        user:
          type: string
          format: email
          description: User identifier, specifically the email address
          example: test@example.com
        tokens:
          allOf:
            - $ref: '#/components/schemas/UserTokens'
        message:
          type: string
          nullable: true
          description: System message regarding the operation
          example: This message is about the operation response. Be safe
        action_needed:
          allOf:
            - $ref: '#/components/schemas/ActionNeeded'
        success:
          type: boolean
          nullable: true
          description: Indicates whether the operation was successful
          example: true
      required: [ user , success ]
    UserTokens:
      nullable: true
      type: object
      properties:
        access_token:
          type: string
          description: Token used for user authentication via API
          example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
        token_type:
          type: string
          description: Token type of the access token
          example: Bearer
        expires_at:
          type: string
          format: date-time
          description: Expiration date and time of the access token in ISO 8601 format.
          example: '2024-10-13T16:30:00Z'
        refresh_token:
          type: string
          description: Token used to renew the refresh token.
          example: refresh987xyz654wvu321tsr210qpo109nml876kji543hgf321
        refresh_expires_at:
          type: string
          format: date-time
          description: Expiration date and time of the refresh token in ISO 8601 format.
          example: '2024-11-12T15:30:00Z'
    ActionNeeded:
      nullable: true
      type: object
      properties:
        type:
          type: string
          nullable: true
          description: Type of the action needed, e.g. 'verify_pin'
          example: verify_pin
        redirectUrl:
          type: string
          nullable: true
          description: URL to redirect the user
          example: https://example.com/redirect
        serviceUrl:
          type: string
          nullable: true
          description: URL of the service related to the action
          example: https://example.com/service
      required: []
    ErrorResponse:
      $ref: './schemas/CommonSchemas.yaml#/ErrorResponse'

paths:
  # Auth
  /v1/user/auth/login:
    post:
      summary: Login with username and password
      description: Authenticates a user and returns access and refresh tokens
      operationId: authLogin
      tags: [ Login ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: Username or user email
                  example: julius.maximus
                password:
                  type: string
                  format: password
                  description: User password
                  example: V3n1V1d1V1c1!
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/login/rules:
    get:
      summary: User login form rules
      description: Validation rules for login form
      operationId: authLoginRules
      tags: [ Login , Form Rules]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/logout:
    post:
      summary: User logout
      description: Invalidates the user's current tokens
      operationId: authLogout
      tags: [ Login ]
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Successful logout
          content:
            application/json:
              schema:
                type: object
                required: [meta, data]
                properties:
                  data:
                    type: object
                    properties:
                      user:
                        $ref: './schemas/CommonSchemas.yaml#/UserEmpty'

                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/signup:
    post:
      summary: Register new user
      description: Creates a new user account in INACTIVE status and sends an email validation message
      operationId: authSignup
      tags: [ Signup ]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
                - password_repeat
              properties:
                username:
                  type: string
                  nullable: true
                  description: > 
                    Unique username, optional (letters, numbers, underscores, and dashes only). 
                    If not provided, the email will be used
                  minLength: 3
                  maxLength: 255
                  pattern: '^[a-zA-Z0-9_-]+$'
                  example: newuser
                email:
                  type: string
                  format: email
                  description: Unique and required email
                  example: newuser@example.com
                password:
                  type: string
                  format: password
                  description: Password (minimum 6 characters, maximum 255)
                  minLength: 6
                  maxLength: 255
                  example: P@ssword123!
                password_repeat:
                  type: string
                  format: password
                  description: Password confirmation (must match password)
                  example: P@ssword123!
      responses:
        '200':
          description: User registered but in inactive status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/signup/rules:
    get:
      summary: Register new user form rules
      description: Validation rules for Register new user form
      operationId: authSignupRules
      tags: [ Signup , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/light-signup:
    post:
      summary: Light user registration
      description: |
        Creates a new user account with **INACTIVE** status and sends a verification email
        using only the provided email address.
      operationId: authLightSignup
      tags: [Light Signup]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Required and must be a valid email address.
                  example: newuser@example.com
      responses:
        '200':
          description: User successfully registered in INACTIVE status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/light-signup/rules:
    get:
      summary: Light user registration form rules
      description: Returns the validation rules for the light user registration form.
      operationId: authLightSignupRules
      tags: [ Light Signup , Form Rules]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules for the light signup form.
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/verification-email:
    post:
      summary: Resend the user email verification message by submitting signup form data
      description: >
        Sends an email verification message to a user with INACTIVE status.
        The username is optional and should only be provided if it was submitted during signup.
        Otherwise, the email will be used as the identifier.
      operationId: authResendEmail
      tags: [ Signup ]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                username:
                  type: string
                  nullable: true
                  description: >
                    Unique username (letters, numbers, underscores, and dashes only).
                    Optional: provide only if it was submitted during signup.
                    If omitted, the email will be used instead.
                  minLength: 3
                  maxLength: 255
                  pattern: '^[a-zA-Z0-9_-]+$'
                  example: newuser
                email:
                  type: string
                  format: email
                  description: Unique and required email address
                  example: newuser@example.com
                password:
                  type: string
                  format: password
                  description: Password (minimum 6 characters, maximum 255)
                  minLength: 6
                  maxLength: 255
                  example: P@ssword123!
      responses:
        '200':
          description: Verification email resent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/verification-email/rules:
    get:
      summary: User email verification form rules
      description: Validation rules for user email verification form
      operationId: authResendEmailRules
      tags: [ Signup , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/verification-email-by-token:
    post:
      summary: Resend the user email verification message using an access token
      description: >
        Sends an email verification message to a user with INACTIVE status.
      operationId: authResendEmailByToken
      tags: [ Signup ]
      security:
        - ApiKeyAuth: []
      parameters:
        - name: token
          in: query
          required: true
          description: Token used for user authentication via API
          example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
          schema:
            type: string
      responses:
        '200':
          description: Verification email resent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/refresh-token:
    post:
      summary: Refresh access token
      description: |
        Obtain a new access token using the refresh token.<br>
        If the refresh token is close to expiration, it will be renewed as well.<br><br>
        <b>Note:</b> always store both tokens because the refresh token can be automatically updated.
      operationId: authRefreshToken
      tags:
        - Token Refresh
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refresh_token
              properties:
                refresh_token:
                  type: string
                  description: Refresh token received at login
                  example: abc123refresh456token789xyz
      responses:
        '200':
          description: Token regenerated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/verify-email:
    get:
      summary: Verify user email
      description: Verifies the user's email inbox via token
      operationId: authVerifyEmail
      tags:
        - Identity Verification
      security:
        - ApiKeyAuth: []
      parameters:
        - name: token
          in: query
          required: true
          description: Verification token sent by email
          schema:
            type: string
      responses:
        '200':
          description: Verification completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/auth/verify-email/rules:
    get:
      summary: Verify user email form rules
      description: Validation rules for verify user email form
      operationId: authVerifyEmailRules
      tags: [ Identity Verification , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # OAuth v1.1.0
  /v1/user/oauth/login:
    post:
      summary: Login via Social OAuth
      description: |
        Validates the OAuth token (Facebook/Google, etc.), verifies user email match and creates/recovers account.<br>
        If the operation requires an additional step (e.g. PIN verification), it is indicated in `need_action`.
      operationId: oauthLogin
      tags:
        - Social Login
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - provider
              properties:
                provider:
                  type: string
                  description: Authentication provider
                  enum: [facebook, google]
                  example: facebook
                token:
                  type: string
                  description: Token issued by the provider
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/oauth/verify-auth:
    post:
      summary: Verify Social authentication via PIN
      description: Verifies the PIN associated with the social authentication process and completes the login by activating the user
      operationId: oauthVerifyAuth
      tags:
        - Identity Verification
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
        - $ref: '#/components/parameters/VerificationToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pin
              properties:
                pin:
                  type: integer
                  description: Verification code sent to the user
                  example: 123456
      responses:
        '200':
          description: Verification completed, user authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/oauth/verify-auth/rules:
    get:
      summary: Verify Social authentication via PIN form rules
      description: Validation rules for verify Social auth PIN form
      operationId: oauthVerifyAuthRules
      tags: [ Identity Verification , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # Password v1.2.0
  /v1/user/password/change:
    post:
      summary: Change password
      description: |
        Changes the authenticated user's password.<br><br>
        <b>Note:</b> always store tokens as they will be regenerated.
      operationId: userChangePassword
      tags:
        - Password change
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - current_password
                - new_password
                - new_password_repeat
              properties:
                current_password:
                  type: string
                  format: password
                  description: Current password
                  example: oldP@ssword123!
                new_password:
                  type: string
                  format: password
                  description: New password (minimum 6 characters)
                  minLength: 6
                  example: newP@ssword123!
                new_password_repeat:
                  type: string
                  format: password
                  description: Confirm new password
                  example: newP@ssword123!
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/password/change/rules:
    get:
      summary: Change password form rules
      description: Validation rules for change password form
      operationId: userChangePasswordRules
      tags: [ Password change , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/password/request-reset:
    post:
      summary: Request password reset
      description: Sends an email with a link to reset the password (email implementation to be completed)
      operationId: passwordRequestReset
      tags:
        - Password Reset
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Registered user email
                  example: user@example.com
      responses:
        '200':
          description: Request sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/password/request-reset/rules:
    get:
      summary: Request password reset form rules
      description: Validation rules for request password reset form
      operationId: passwordRequestResetRules
      tags: [ Password Reset , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/password/validate-token:
    get:
      summary: Validate reset token
      description: Checks if a password reset token is valid and not expired
      operationId: passwordValidateToken
      tags:
        - Password Reset
      security:
        - ApiKeyAuth: []
      parameters:
        - name: token
          in: query
          required: true
          description: Password reset token to validate
          schema:
            type: string
            example: abc123reset456token789_1234567890
      responses:
        '200':
          description: Valid token
          content:
            application/json:
              schema:
                type: object
                required: [meta, data]
                properties:
                  data:
                    type: object
                    properties:
                      user:
                        $ref: './schemas/CommonSchemas.yaml#/UserEmpty'

                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/password/reset:
    post:
      summary: Reset password using token
      description: Sets a new password using the reset token
      operationId: passwordReset
      tags:
        - Password Reset
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - password
                - password_repeat
              properties:
                token:
                  type: string
                  description: Reset token received via email
                  example: abc123reset456token789_1234567890
                password:
                  type: string
                  format: password
                  description: "New password (min 8 chars, must include uppercase, lowercase, number, and symbol)."
                  minLength: 8
                  example: NewP@ssword123!
                password_repeat:
                  type: string
                  format: password
                  description: Confirm new password
                  example: NewP@ssword123!
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/password/reset/rules:
    get:
      summary: Reset password form rules
      description: Validation rules for reset password form
      operationId: passwordResetRules
      tags: [ Password Reset , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # Account v1.3.0
  /v1/user/account/light-update:
    patch:
      summary: Essential user account update
      description: Update first name, last name, and password
      operationId: accountLightUpdate
      tags: [ Account ]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - firstname
                - lastname
                - password
                - password_repeat
                - accept_privacy_policy
              properties:
                firstname:
                  type: string
                  description: User's first name
                  example: Gaius
                lastname:
                  type: string
                  description: User's last name
                  example: Julius Caesar
                password:
                  type: string
                  format: password
                  description: Password (minimum 6 characters, maximum 255)
                  minLength: 6
                  maxLength: 255
                  example: P@ssword123!
                password_repeat:
                  type: string
                  format: password
                  description: Password confirmation (must match password)
                  example: P@ssword123!
                accept_privacy_policy:
                  type: boolean
                  description: User must accept the privacy policy
                  example: true
      responses:
        '200':
          description: User data updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/user/account/light-update/rules:
    get:
      summary: Account light update form rules
      description: Validation rules for Account light update form
      operationId: accountLightUpdateRules
      tags: [ Account , Form Rules ]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Validation rules
          content:
            application/json:
              schema:
                $ref: './schemas/CommonSchemas.yaml#/FormValidationResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'