openapi: 3.0.3
info:
  version: 1.0.0
  title: Common Hosted Form Service (CHEFS)
  description: >-
    The API for an application for teams to create, manage and publish web
    forms. These back-end operations can work for different form builder tools
    that define the form as a json schema. Form management features include
    role-based access for administrators, form versioning, submission review and
    export, as well as notifications, document generation and reporting.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Forminators
    email: submit.digital@gov.bc.ca
externalDocs:
  description: Project Readmes
  url: https://github.com/bcgov/common-hosted-form-service
servers:
  - url: /app/api/v1
    description: This Server
security:
  - BearerAuth: []
    OpenID: []
tags:
  - name: Form
    description: >-
      The API paths in this section are used to read and write data that make up
      a web form, for example, the form schema object, metadata, and related
      settings
  - name: Form API
    description: >-
      This section supports the creation, management and removal of form scoped
      API Key secrets. CHEFS endpoints which permit Basic Authentication use the
      Form ID as username and the API Key as the password.
  - name: Version
    description: >-
      The API supports versioning of forms. This allows a user to manage
      multiple versions of a form design and, for example, publish a specific
      version of a form.
  - name: Draft
    description: >-
      This section of the API includes endpoints used to perform various
      operations related to form drafts, for example create or publish a draft
      from a specific version of a form.
  - name: Document Templates
    description: >
      Documents can be generated using the Common Document Generation Service
      ([CDOGS](https://bcgov.github.io/common-service-showcase/services/cdogs.html)).
      Form submission data is merged into a user-defined _document template_ to
      create the document.

      > This is an experimental API that is currently only MVP, and it will
      change rapidly. It is best to avoid using these endpoints (outside of the
      CHEFS app itself) until they stabilize.


      Currently only a single document template per form is supported by the
      CHEFS application:
        1. The `POST /forms/{formId}/documentTemplates` route is used to create
           a document template for a form.
        2. Subsequent calls to the `POST` route should be paired with calls to
           the `DELETE` route to delete the previously active template.
        
      Submission metadata is available for use in the document templates:
        - `{d.chefs.submissionId}`: the unique identifier for the submission,
          such as `3cb9acc7-cfd8-4491-b091-1277bc0ec303` 
        - `{d.chefs.confirmationId}`: The uppercased first eight characters of
          the `submissionId`, such as `3CB9ACC7`
        - `{d.chefs.formVersion}`: The numeric version of the form that was used
          to create the submission, such as `1`
  - name: Print Configuration
    description: >
      Print configuration allows forms to be configured with different print
      behaviors. When set to "default", users can choose between browser print
      or template-based document generation. When set to "direct", users will
      print directly using a pre-configured document template, generating a PDF
      output.
  - name: Submission
    description: >-
      These API endpoints handle the input data provided by a user that
      completes the form, for example, writing the form data to the database, or
      exporting form submissions created during a defined time period.
  - name: Status
    description: >-
      These API endpoints handle operations to update and retrieve statuses and
      notes on a submission, and status code management for a Form.
  - name: Email Recipients
    description: >-
      These API endpoints handle operations to update and retrieve email
      recipients for a form when the status is set to REVISING or COMPLETED.
  - name: Files
    description: API endpoints to upload and retrieve files stored in CHEFS.
  - name: User
    description: >-
      The section includes API endpoints for carrying out operations with data
      related to users of the application.
  - name: Role
    description: >-
      The API includes endpoints for managing roles assigned to users. A role,
      for example, 'Form Designer' or 'Submission Reviewer' will often
      correspond to the business functions of a user's job. Roles have a group
      of related permissions that are used to control access to a defined set of
      features of and application.
  - name: Permission
    description: >-
      The API uses Permissions to control access to a defined set of features of
      and application, for example, reading form submissions or updating the
      design of a form. Permissions are assigned to roles.
  - name: RBAC
    description: >-
      This section of the API documents the API endpoints related to Role-based
      Access Control (RBAC). RBAC is a method of restricting access based on
      roles. These endpoints handle a combination of user, role and permission
      data as well as the access settings for a published form.
  - name: Admin
    description: >-
      These API endpoints are used for elevated permission administrative calls.
      All calls are secured by a role that operational team members will be
      granted and allow fetching some details about forms without needing a
      user->form permission.
  - name: Health
    description: >-
      These API endpoints are used for for health checks of CHEFS and its
      required services.
  - name: Common Services
    description: >-
      These API endpoints are used to access the CSS (Common Service Showcase)
      services, such as the single sign on service.
paths:
  /forms:
    get:
      summary: List all forms
      operationId: listForms
      tags:
        - Form
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: query
          name: active
          schema:
            type: boolean
          description: filter forms by active status
          example: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Form'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new form
      operationId: createForm
      tags:
        - Form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/FormBasic'
                - $ref: '#/components/schemas/FormSchema'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormBasic'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}:
    get:
      summary: Get details of a form (and metadata for versions)
      operationId: readForm
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Form
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a form
      operationId: updateForm
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Form
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormBasic'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: (Soft) Delete a form
      operationId: deleteForm
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Form
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '204':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormBasic'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/apiKey:
    get:
      summary: Get current API Key
      description: Get the active api key secret for a form
      operationId: readApiKey
      tags:
        - Form API
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Create/Replace API Key
      description: Create or replace api key secret for a form
      operationId: createReplaceApiKey
      tags:
        - Form API
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete API Key
      description: Delete the api key secret for a form
      operationId: deleteApiKey
      tags:
        - Form API
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/apiKey/filesApiAccess:
    put:
      summary: Set the API key access to submitted files
      description: Enable/disable access to submitted files using the API key.
      operationId: filesApiAccess
      tags:
        - Form API
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/documentTemplates:
    get:
      summary: Get all document templates for a form
      description: >
        Gets an array containing all the document template metadata for the
        given form.

        > Objects returned by this route do not include the `template` field. If
        this document template file is needed, use the `id` field from the
        returned metadata to make a call to
        `/forms/{formId}/documentTemplates/{documentTemplateId}`.
      operationId: readDocumentTemplates
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Document Templates
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentTemplateResponseBasic'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a document template
      description: >
        Creates a document template for a form. This makes it easier for users
        to generate documents, as the template is associated with the form and
        does not need to be distributed to every user.
      operationId: updateDocumentTemplate
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Document Templates
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/documentTemplates/{documentTemplateId}:
    get:
      summary: Get a document template
      description: >
        Gets a document template for the given form. The response will include
        the `template` field, which is the actual document template file.
      operationId: readDocumentTemplate
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Document Templates
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/documentTemplateIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplateResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: (Soft) Delete a document template
      description: >
        Marks a document template as no longer being active. In this state the
        document template is essentially treated as if it does not exist. It
        will not be returned by the `GET` routes and cannot otherwise be used.
      operationId: deleteDocumentTemplate
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Document Templates
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/documentTemplateIdParam'
      responses:
        '204':
          description: OK
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/printConfig:
    get:
      summary: Get print configuration for a form
      description: >
        Gets the print configuration for a form. Returns `null` if no print
        configuration has been set for the form.
      operationId: readPrintConfig
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Print Configuration
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintConfigResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Create or update print configuration for a form
      description: >
        Creates or updates the print configuration for a form. When `code` is
        set to `direct`, a `templateId` must be provided and must reference an
        active document template for the form. When `code` is set to `default`,
        the `templateId` and `outputFileType` fields are ignored.
      operationId: upsertPrintConfig
      security:
        - BearerAuth: []
          OpenID: []
      tags:
        - Print Configuration
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintConfigRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintConfigResponse'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/export:
    get:
      summary: Export submissions for a form
      operationId: export
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - in: query
          name: format
          schema:
            type: string
          description: chosen format for the submission data exported
          example: csv
          required: true
        - in: query
          name: type
          schema:
            type: string
          description: the category of data exported
          example: submissions
          required: true
        - in: query
          name: version
          schema:
            type: string
          description: >-
            The form version number. If the export format is json and not csv,
            then setting this to 0 will export all versions.
          example: 1
          required: true
        - in: query
          name: preference
          schema:
            type: object
          example: >-
            {"minDate":"2020-12-17T08:00:00Z","maxDate":"2020-12-18T08:00:00Z","updatedMinDate":"2020-12-17T08:00:00Z","updatedMaxDate":"2020-12-18T08:00:00Z"}
          description: form submissions export preferences
        - in: query
          name: deleted
          schema:
            type: boolean
          description: Set to true to return deleted submissions
          example: false
        - in: query
          name: drafts
          schema:
            type: boolean
          description: Set to true to return draft submissions
          example: false
        - in: query
          name: columns
          schema:
            type: array
            description: >-
              List of form level columns (Only Allowed `deleted`, `draft`,
              `updatedAt`) to be included, others will be ignored
            example:
              - deleted,
              - draft,
              - updatedAt
            items:
              type: string
        - in: query
          name: status
          schema:
            type: string
          description: Submission status to be filtered based on
          example: COMPLETED
          required: false
      responses:
        '200':
          description: Export file created for download
          headers:
            content-type:
              description: Response header
              schema:
                type: object
              example: text/json; charset=utf-8
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            text/csv:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormSubmissionExport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/export/fields:
    post:
      summary: >-
        Export submissions for a form with the ability to select fields to
        export if CSV is selected.
      operationId: exportWithFields
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSubmissionExportWithFields'
      responses:
        '200':
          description: Export file created for download
          headers:
            content-type:
              description: Response header
              schema:
                type: object
              example: text/json; charset=utf-8
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            text/csv:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormSubmissionExport'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/options:
    get:
      summary: Get pre-flight details for a form
      operationId: readFormOptions
      tags:
        - Form
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormOptions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/versions/{formVersionId}:
    get:
      summary: Get a single form version
      operationId: readVersion
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Version
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormVersion'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/versions/{formVersionId}/fields:
    get:
      summary: Get a list of valid form fields in this form version
      operationId: readVersionFields
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Version
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormVersionFields'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/version:
    get:
      summary: Get published version of a form
      operationId: readPublishedForm
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Version
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/versions/{formVersionId}/publish:
    post:
      summary: Publish a version of a form
      operationId: publishVersion
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Version
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
        - in: query
          name: unpublish
          schema:
            type: boolean
          example: true
          required: false
          description: Should this version of the form be unpublished
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormVersionBasic'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/drafts:
    get:
      summary: List drafts for a form
      operationId: listDrafts
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Draft
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormDraft'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a draft from a form version
      operationId: createDraft
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Draft
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                formVersionId:
                  type: string
                  format: uuid
                  description: ID of the form version used for this draft
                  example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
                schema:
                  $ref: '#/components/schemas/FormSchema'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDraft'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/drafts/{formVersionDraftId}:
    get:
      summary: Get a form draft
      operationId: readDraft
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Draft
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionDraftIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDraft'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a form draft
      operationId: updateDraft
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Draft
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionDraftIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schema:
                  $ref: '#/components/schemas/FormSchema'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDraft'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a form draft
      operationId: deleteDraft
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Draft
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionDraftIdParam'
      responses:
        '204':
          description: OK
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/drafts/{formVersionDraftId}/publish:
    post:
      summary: Publish a form draft
      operationId: publishDraft
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Draft
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionDraftIdParam'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormVersionBasic'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/submissions:
    get:
      summary: List submissions for a form
      operationId: listFormSubmissions
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - in: query
          name: fields
          schema:
            type: string
            example: textField1,checkbox1,radioGroup1,email1
          description: >-
            A list of form fields to search on. Refer to the related
            `versions/{formVersionId}/fields` endpoint for a list of valid
            values to query for. The list should be comma separated.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormSubmissionSummary'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/versions/{formVersionId}/submissions:
    get:
      summary: List submissions from a form version
      operationId: listSubmissions
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormSubmission'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new form submission
      operationId: createSubmission
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSubmissionBasic'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmission'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/versions/{formVersionId}/multiSubmission:
    post:
      summary: Upload multiple draft submissions
      operationId: uploadMultipleDraft
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSubmissionMultiple'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmissionResponseMultiple'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/versions/{formVersionId}/submissions/discover:
    get:
      summary: List field value submissions from a form version
      description: >-
        A queryable endpoint for acquiring a specific subset of data from the
        submissions
      operationId: listDiscoverSubmissions
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - $ref: '#/components/parameters/formVersionIdParam'
        - in: query
          name: fields
          schema:
            type: string
            example: textField1,checkbox1,radioGroup1,email1
          description: >-
            A list of form fields to search on. Refer to the related `/fields`
            endpoint for a list of valid values to query for. The list can be
            comma separated or by repeating the same fields query multiple
            times.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormSubmissionDiscover'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}:
    get:
      summary: Get a form submission
      operationId: readSubmission
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionFormVersion'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a form submission
      operationId: updateSubmission
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSubmissionBasic'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: (Soft) delete a form submission
      operationId: deleteSubmission
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionFormVersionDeleted'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/email:
    post:
      summary: Email a message with link to a submission
      operationId: emailSubmission
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
        - in: header
          name: Referer
          description: URL of webpage where email was requested
          schema:
            type: string
          required: true
          example: >-
            https://submit.digital.gov.bc.ca/app/form/success?s=7d66664b-87c5-4df8-ba7c-a6fb7d62c379
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  example: jsmith@email.ca
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/edits:
    get:
      summary: Get an audit list of edits to a submission
      operationId: readSubmissionEdits
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubmissionEditMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/options:
    get:
      summary: Get pre-flight details for a form submission
      operationId: readSubmissionOptions
      tags:
        - Submission
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionFormVersionOptions'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/statusCodes:
    get:
      summary: List status codes for a form
      operationId: getStatusCodes
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatusCodes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/status:
    get:
      summary: Get the list of status history for a submission
      operationId: readSubmissionStatus
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubmissionStatusHistory'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Add a new status to a submission
      description: >-
        Adds a new status to a submission, and optionally provides email
        notification depending

        on the status being assigned.
      operationId: addSubmissionStatus
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionStatus'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionStatusHistory'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/template/{documentTemplateId}/render:
    get:
      summary: Generate document from submission ID and template ID
      description: >-
        Uses form submission data (given the form submission ID) and a document
        template (given the document template ID) and generates a document
        containing the submission data.

        #### Common Document Generation Service (CDOGS)

        This endpoint is a passthrough to CDOGS. Instead of using *BasicAuth* to
        call this endpoint, it is highly recommended that you [directly call
        CDOGS](https://bcgov.github.io/common-service-showcase/services/cdogs.html).
        Benefits of calling CDOGS directly from your application:
          - avoid CHEFS API rate limiting restrictions
          - avoid CHEFS API timeout restrictions (for large documents)
          - better performance (direct call instead of passthrough)
          - ability to use the CDOGS template cache
          - direct support from the CDOGS team for your specific Client ID
      operationId: templateIdSubmissionIdRender
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Document Templates
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
        - $ref: '#/components/parameters/documentTemplateIdParam'
        - in: query
          name: convertTo
          schema:
            type: string
          description: file type to convert to
          example: pdf
      responses:
        '200':
          description: Returns the document template with merged variables
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Raw binary-encoded response
          headers:
            Content-Disposition:
              schema:
                type: string
              description: >-
                Indicates if a browser should render this resource inline or
                treat as an attachment for download
              example: attachment; filename=file.pdf
            Content-Type:
              schema:
                type: string
              description: The MIME-type of the binary file payload
              example: application/pdf
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/template/render:
    post:
      summary: Generate document from submission ID and template object
      description: >-
        Merges data from a form submission into a document template.

        #### Common Document Generation Service (CDOGS)

        This endpoint is a passthrough to CDOGS. Instead of using *BasicAuth* to
        call this endpoint, it is highly recommended that you [directly call
        CDOGS](https://bcgov.github.io/common-service-showcase/services/cdogs.html).
        Benefits of calling CDOGS directly from your application:
          - avoid CHEFS API rate limiting restrictions
          - avoid CHEFS API timeout restrictions (for large documents)
          - better performance (direct call instead of passthrough)
          - ability to use the CDOGS template cache
          - direct support from the CDOGS team for your specific Client ID
      operationId: templateObjectSubmissionIdRender
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Document Templates
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      requestBody:
        description: Fields required to generate a document
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateRenderObject'
      responses:
        '200':
          description: Returns the document template with merged variables
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Raw binary-encoded response
          headers:
            Content-Disposition:
              schema:
                type: string
              description: >-
                Indicates if a browser should render this resource inline or
                treat as an attachment for download
              example: attachment; filename=file.pdf
            Content-Type:
              schema:
                type: string
              description: The MIME-type of the binary file payload
              example: application/pdf
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submissions/{formSubmissionId}/notes:
    get:
      summary: Get the list of notes for a submission
      operationId: readSubmissioNotes
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Note'
                    - $ref: '#/components/schemas/TimeStampUserData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Add a note to a submission
      operationId: addSubmissionNote
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Note'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /submission/{formSubmissionId}/emailRecipients:
    get:
      summary: Get email recipients
      operationId: getEmailRecipients
      tags:
        - Email Recipients
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRecipients'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Add email recipients
      operationId: addEmailRecipients
      tags:
        - Email Recipients
      parameters:
        - $ref: '#/components/parameters/formSubmissionIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRecipients'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRecipients'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files:
    post:
      summary: Upload a file
      operationId: fileUpload
      tags:
        - Files
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: file_name-5b26db5a-8388-4c01-b728-d0d098f815ba.pdf
                  description: The desired file name
                files:
                  type: string
                  format: binary
                  description: The actual files to upload
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileUpload'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{fileId}:
    get:
      summary: Get a file
      operationId: fileGet
      security:
        - BasicAuth: []
        - BearerAuth: []
          OpenID: []
      tags:
        - Files
      parameters:
        - $ref: '#/components/parameters/fileIdParam'
      responses:
        '200':
          description: The returned binary file
          content:
            application/<type>:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a file
      operationId: fileDelete
      tags:
        - Files
      parameters:
        - $ref: '#/components/parameters/fileIdParam'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /permissions:
    get:
      summary: List all permissions
      operationId: listPermissions
      tags:
        - Permission
      security:
        - BearerAuth: []
          OpenID:
            - admin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Permission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /permissions/{code}:
    get:
      summary: Get a permission
      operationId: readPermission
      tags:
        - Permission
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: path
          name: code
          schema:
            type: string
          required: true
          description: code of the permission to fetch
          example: submission_read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /roles:
    get:
      summary: List all roles
      operationId: listRoles
      tags:
        - Role
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /roles/{code}:
    get:
      summary: Get a role
      operationId: getRole
      tags:
        - Role
      parameters:
        - in: path
          name: code
          schema:
            type: string
          required: true
          description: code of the role to fetch
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/current:
    get:
      summary: Get current user details
      operationId: getCurrentUser
      tags:
        - RBAC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CurrentUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/current/forms:
    get:
      summary: Get forms/roles/permissions for current user
      operationId: getCurrentUserForms
      tags:
        - RBAC
      parameters:
        - in: query
          name: formId
          schema:
            type: string
            format: uuid
            example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
          description: form ID
        - in: query
          name: active
          schema:
            type: boolean
          example: true
          description: is the form active flag
        - in: query
          name: idps
          schema:
            type: string
        - in: query
          name: accessLevels
          schema:
            type: string
          description: filter on the user access level for the form (public, idp, team)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/UserForm'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/current/submissions:
    get:
      summary: Get submissions/roles/permissions for current user
      operationId: getCurrentUserSubmissions
      tags:
        - RBAC
      parameters:
        - in: query
          name: formId
          schema:
            type: string
            format: uuid
            example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
          description: form ID
        - in: query
          name: formSubmissionId
          schema:
            type: string
            format: uuid
            example: c6455376-382c-439d-a811-0381a012d696
          description: submission ID
        - in: query
          name: userId
          schema:
            type: string
            format: uuid
            example: c6455376-382c-439d-a811-0381a012d696
          description: user ID
        - in: query
          name: active
          schema:
            type: boolean
          example: true
          description: to include active or deleted submissions or not
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserSubmission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/idps:
    get:
      summary: Get a list of identity providers
      operationId: getIdentityProviders
      tags:
        - RBAC
      parameters:
        - in: query
          name: active
          schema:
            type: boolean
          example: true
          description: is the identity provider active
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProvider'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/forms:
    get:
      summary: Get a list of users and roles for a form
      operationId: getFormUsers
      tags:
        - RBAC
      parameters:
        - in: query
          name: formId
          schema:
            type: string
            format: uuid
            example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
          description: form ID
          required: true
        - in: query
          name: userId
          schema:
            type: string
          description: user ID
        - in: query
          name: idpUserId
          schema:
            type: string
          description: user identity provider id
        - in: query
          name: username
          schema:
            type: string
          description: user username
        - in: query
          name: fullName
          schema:
            type: string
          description: user fullName
        - in: query
          name: firstName
          schema:
            type: string
          description: user firstName
        - in: query
          name: lastName
          schema:
            type: string
          description: user lastName
        - in: query
          name: email
          schema:
            type: string
          description: user email
        - in: query
          name: formName
          schema:
            type: string
          description: form name
        - in: query
          name: active
          schema:
            type: boolean
          example: true
          description: is the form active flag
        - in: query
          name: idps
          schema:
            type: string
          description: identity provider (idp field) associated with form
        - in: query
          name: roles
          schema:
            type: string
          description: roles (code field) user has on form
        - in: query
          name: permissions
          schema:
            type: string
          description: permissions (code field) user has on form
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Set user roles for a form
      operationId: setFormUsers
      tags:
        - RBAC
      parameters:
        - in: query
          name: formId
          schema:
            type: string
            format: uuid
            example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
          description: form id
          required: true
        - in: query
          name: userId
          schema:
            type: string
            format: uuid
            example: d7455376-382c-439d-a811-0381a012d696
          description: user id
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FormRoleUser'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/submissions:
    get:
      summary: Get a list of users and permissions for a submission
      operationId: getSubmissionUsers
      tags:
        - RBAC
      parameters:
        - in: query
          name: formSubmissionId
          schema:
            type: string
            format: uuid
            example: c6455376-382c-439d-a811-0381a012d696
          description: submission ID
          required: true
        - in: query
          name: userId
          schema:
            type: string
          description: user ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAccessSubmission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Set permissions for a user on a submission
      operationId: setSubmissionUser
      tags:
        - RBAC
      parameters:
        - in: query
          name: formSubmissionId
          schema:
            type: string
            format: uuid
            example: c6455376-382c-439d-a811-0381a012d696
          description: submission id
          required: true
        - in: query
          name: userId
          schema:
            type: string
          description: user ID
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: SUBMISSION_UPDATE
              description: >-
                an array of the sumbission permissions to apply to this user.
                Set an empty array to remove.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAccessSubmission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rbac/users:
    get:
      summary: Get a list of forms and roles for a user
      operationId: getUserForms
      tags:
        - RBAC
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: query
          name: userId
          schema:
            type: string
          description: user id
        - in: query
          name: idpUserId
          schema:
            type: string
          description: user identity provider id
        - in: query
          name: username
          schema:
            type: string
          description: user username
        - in: query
          name: fullName
          schema:
            type: string
          description: user fullName
        - in: query
          name: fullname
          schema:
            type: string
          description: user username
        - in: query
          name: firstName
          schema:
            type: string
          description: user firstName
        - in: query
          name: lastName
          schema:
            type: string
          description: user lastName
        - in: query
          name: email
          schema:
            type: string
          description: user email
        - in: query
          name: formId
          schema:
            type: string
            format: uuid
            example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
          description: form id
          required: true
        - in: query
          name: formName
          schema:
            type: string
          description: form name
        - in: query
          name: active
          schema:
            type: boolean
          example: true
          description: is the form active flag
        - in: query
          name: idps
          schema:
            type: string
          description: identity provider (idp field) associated with form
        - in: query
          name: roles
          schema:
            type: string
          description: roles (code field) user has on form
        - in: query
          name: permissions
          schema:
            type: string
          description: permissions (code field) user has on form
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Set form roles for a user
      operationId: setUserForms
      tags:
        - RBAC
      parameters:
        - in: query
          name: userId
          schema:
            type: string
          description: user id
          required: true
        - in: query
          name: formId
          schema:
            type: string
            format: uuid
            example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
          description: form id
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FormRoleUser'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users:
    get:
      summary: Get a list of users and their roles
      operationId: listUsers
      tags:
        - User
      parameters:
        - in: query
          name: idpUserId
          schema:
            type: string
          description: user identity provider id
        - in: query
          name: username
          schema:
            type: string
          description: user username
        - in: query
          name: fullName
          schema:
            type: string
          description: user fullName
        - in: query
          name: firstName
          schema:
            type: string
          description: user firstName
        - in: query
          name: lastName
          schema:
            type: string
          description: user lastName
        - in: query
          name: email
          schema:
            type: string
          description: user email
        - in: query
          name: search
          schema:
            type: string
          description: string to match against username, fullName and Email
        - in: query
          name: idpCode
          schema:
            type: string
          description: Filter results to only users with specified idpCode
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}:
    get:
      summary: Get a user and their roles
      operationId: readUser
      tags:
        - User
      parameters:
        - in: path
          name: userId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: user ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/preferences:
    get:
      summary: Get the preferences for current user
      description: Fetches all known preferences for the current user
      operationId: readUserPreferences
      tags:
        - User
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPreferences'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update the preferences for current user
      description: Updates all known preferences for the current user
      operationId: updateUserPreferences
      tags:
        - User
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPreferences'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPreferences'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete all preferences for current user
      description: Deletes all known preferences for the current user
      operationId: deleteUserPreferences
      tags:
        - User
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/preferences/forms/{formId}:
    get:
      summary: Get the form preferences for current user
      description: Fetches preferences for the current user specific to this form
      operationId: readUserFormPreferences
      tags:
        - User
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/UserFormPreferences'
                  - $ref: '#/components/schemas/TimeStampUserData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update the form preferences for current user
      description: Updates preferences for the current user specific to this form
      operationId: updateUserFormPreferences
      tags:
        - User
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormPreferences'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/UserFormPreferences'
                  - $ref: '#/components/schemas/TimeStampUserData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete all form preferences for current user
      description: Deletes preferences for the current user specific to this form
      operationId: deleteUserFormPreferences
      tags:
        - User
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/labels:
    get:
      summary: Get all the labels associated with the current user
      description: Fetches the labels for the current user to this form
      operationId: readUserLabels
      tags:
        - User
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update user labels
      operationId: updateUserLabels
      tags:
        - User
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Label'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/forms:
    get:
      summary: List all forms in the system
      operationId: adminListForms
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: query
          name: active
          schema:
            type: boolean
          description: filter forms by active status
          example: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Form'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/forms/{formId}:
    get:
      summary: Get top level details of a form
      operationId: adminReadForm
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormBasic'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/forms/{formId}/apiKey:
    get:
      summary: Get Form API Key
      description: Get the active api key details for a form
      operationId: adminReadApiDetails
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormApiDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete Form API Key
      description: Delete the api key secret for a form
      operationId: adminDeleteApiKey
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/forms/{formId}/restore:
    put:
      summary: Un-delete a soft deleted form
      operationId: adminRestoreForm
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserForm'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/forms/{formId}/formUsers:
    get:
      summary: Get the list of users for the active forms in the system
      operationId: adminReadFormUsers
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormUserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/forms/{formId}/addUser:
    put:
      summary: Add user permissions to a form
      operationId: adminAddUser
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - in: query
          name: userId
          schema:
            type: string
          description: The user to add permissions to
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FormRoleUser'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/users:
    get:
      summary: Get the list of users
      operationId: adminReadUsers
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/users/{userId}:
    get:
      summary: Get a user
      operationId: adminReadUser
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: path
          name: userId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: user ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/encryptionKey/algorithms:
    get:
      summary: Get the list of encryption algorithms
      operationId: listEncryptionAlgorithms
      security:
        - BearerAuth: []
          OpenID: []
      tags:
        - Form
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: code for encryption Algorithm
                    display:
                      type: string
                      description: display for encryption Algorithm
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/encryptionKey/{formEncryptionKeyId}:
    get:
      summary: Get the encryption key for a form
      operationId: readEncryptionKey
      security:
        - BearerAuth: []
          OpenID: []
      tags:
        - Form
      parameters:
        - in: path
          name: formId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form ID
          required: true
        - in: path
          name: formEncryptionKeyId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form encryption key ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptionKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/eventStreamConfig:
    get:
      summary: Get a form's event stream configuration
      operationId: readEventStreamConfig
      security:
        - BearerAuth: []
          OpenID: []
      tags:
        - Form
      parameters:
        - in: path
          name: formId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventStreamConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/externalAPIs/algorithms:
    get:
      summary: List available algorithms for External API encryption
      operationId: listExternalAPIAlgorithms
      security:
        - BearerAuth: []
      tags:
        - ExternalApi
      parameters:
        - in: path
          name: formId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: code for encryption Algorithm
                    display:
                      type: string
                      description: display for encryption Algorithm
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/externalAPIs/statusCodes:
    get:
      summary: List status codes for External APIs
      operationId: listExternalAPIStatusCodes
      security:
        - BearerAuth: []
      tags:
        - ExternalApi
      parameters:
        - in: path
          name: formId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: code for Status
                    display:
                      type: string
                      description: display for Status
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/externalAPIs:
    get:
      summary: List External API configurations for form
      operationId: listExternalAPIs
      security:
        - BearerAuth: []
      tags:
        - ExternalApi
      parameters:
        - in: path
          name: formId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form ID
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExternalApi'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new External API configuration
      operationId: createExternalAPI
      tags:
        - ExternalApi
      parameters:
        - in: path
          name: formId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: form ID
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ExternalApi'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApi'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /forms/{formId}/externalAPIs/{externalAPIId}:
    put:
      summary: Update an External API configuration
      operationId: updateExternalAPI
      security:
        - BearerAuth: []
          OpenID: []
      tags:
        - ExternalApi
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - in: path
          name: externalAPIId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: external API ID
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalApi'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApi'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete an External API configuration
      operationId: deleteExternalAPI
      security:
        - BearerAuth: []
          OpenID: []
      tags:
        - ExternalApi
      parameters:
        - $ref: '#/components/parameters/formIdParam'
        - in: path
          name: externalAPIId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: external API ID
          required: true
      responses:
        '204':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /proxy/external:
    get:
      summary: Call a GET on an External API and return the results
      operationId: callExternalApi
      tags:
        - ExternalApi
      parameters:
        - in: header
          name: X-CHEFS-PROXY-DATA
          schema:
            type: string
            format: hex
          required: true
        - in: header
          name: X-CHEFS-EXTERNAL-API-NAME
          schema:
            type: string
            example: BC Registries Number Lookup
          required: true
        - in: header
          name: X-CHEFS-EXTERNAL-API-PATH
          schema:
            type: string
            example: /path/to/api?qs=val
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '407':
          $ref: '#/components/responses/ApiNotApproved'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /proxy/headers:
    post:
      summary: Generate encrypted headers for External API
      operationId: generateProxyHeaders
      security:
        - BearerAuth: []
      tags:
        - ExternalApi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyInfo'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/externalAPIs:
    get:
      summary: Get list of External APIs
      operationId: adminGetExternalAPIs
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdminExternalApi'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/externalAPIs/statusCodes:
    get:
      summary: Get list of Status Codes for External API
      operationId: adminGetExternalAPIStatusCodes
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: code for Status
                    display:
                      type: string
                      description: display for Status
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /admin/externalAPIs/{externalAPIId}:
    put:
      summary: Update an External API
      operationId: adminUpdateExternalAPI
      tags:
        - Admin
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: path
          name: externalAPIId
          schema:
            type: string
            example: bea3b705-1de5-4f4e-a4e6-0716b7674132
          description: external API ID
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminExternalApi'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminExternalApi'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /status:
    get:
      summary: Get the status of the CHEFS and its dependencies
      description: >-
        Returns the status of the CHEFS service and its dependencies, such as
        database connectivity, external APIs, and other critical components.
        Useful for monitoring and health checks.
      operationId: getStatus
      tags:
        - Health
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatus'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cs/css/idir/users:
    get:
      summary: List all idir users
      operationId: queryIdirUsers
      tags:
        - Common Services
      security:
        - BearerAuth: []
          OpenID:
            - admin
      parameters:
        - in: query
          name: firstName
          schema:
            type: string
          description: filter by first name
          example: Jane
        - in: query
          name: lastName
          schema:
            type: string
          description: filter by last name
          example: Smith
        - in: query
          name: email
          schema:
            type: string
          description: filter by email
          example: jane.smith@example.com
        - in: query
          name: guid
          schema:
            type: string
          description: filter by GUID
          example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CssUserIdir'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RateLimit:
      schema:
        type: string
      description: >-
        Indicates the remaining number of allowed API calls within the remaining
        window. In the example, 18 more requests are allowed within the 45
        seconds that remain in the window. When the window resets after 45
        seconds then the "remaining" will be reset to "limit".
      example: limit=20, remaining=18, reset=45
    RateLimit-Policy:
      schema:
        type: string
      description: >-
        Indicates how many API calls can be made within a "window" of time.
        Additional API calls within the window will result in HTTP 429
        responses. In the example, 20 requests are allowed within a 60 second
        window.
      example: 20;w=60
    retry-after:
      schema:
        type: integer
      description: >-
        Only returned when the rate limit is exceeded (HTTP 429). Indicates the
        number of seconds before the window resets, after which API calls will
        again be allowed. In the example, 13 seconds remain before the window is
        reset.
      example: 13
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OpenID:
      type: openIdConnect
      openIdConnectUrl: >-
        https://loginproxy.gov.bc.ca/auth/realms/standard/.well-known/openid-configuration
  parameters:
    documentTemplateIdParam:
      in: path
      name: documentTemplateId
      description: ID of the document template.
      schema:
        type: string
        format: uuid
      required: true
      example: 7a61407b-2c00-467d-9dd5-f9f060779c5b
    fileIdParam:
      in: path
      name: fileId
      description: ID of the file.
      schema:
        type: string
        format: uuid
      example: 3cb9acc7-cfd8-4491-b091-1277bc0ec303
      required: true
    formIdParam:
      in: path
      name: formId
      description: ID of the form.
      schema:
        type: string
        format: uuid
      required: true
      example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
    formVersionIdParam:
      in: path
      name: formVersionId
      description: ID of the form version.
      schema:
        type: string
        format: uuid
      example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
      required: true
    formVersionDraftIdParam:
      in: path
      name: formVersionDraftId
      description: ID of the draft form version.
      schema:
        type: string
        format: uuid
      example: b2e11d09-30fe-4c4c-9375-5a9de0dc2e9e
      required: true
    formSubmissionIdParam:
      in: path
      name: formSubmissionId
      description: ID of the submission.
      schema:
        type: string
        format: uuid
      example: 3cb9acc7-cfd8-4491-b091-1277bc0ec303
      required: true
  schemas:
    AdminExternalApi:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of ExternalApi.
          example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
        formId:
          type: string
          format: uuid
          description: Form ID this ExternalApi belongs to.
          example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
        name:
          type: string
          description: Name of the ExternalApi - unique per form.
          example: BC Registries Number Lookup
        ministry:
          type: string
          description: Ministry Name of Form
          example: CITZ
        formName:
          type: string
          description: Name of the Form using the External API
          example: My Form
        endpointUrl:
          type: string
          format: url
          description: Endpoint URL of the External API - the api to call.
          example: https://bcreg.com/v1/lookup
        code:
          type: string
          description: Status code.
          example: APPROVED
        display:
          type: string
          description: Status code display value.
          example: Approved
        allowSendUserToken:
          type: boolean
          description: Set by CHEFS Admin, true allows the sendUserToken to be set to true
    CssUserIdir:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              username:
                type: string
                description: ID of the user
                example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l@idir
              email:
                type: string
                example: jsmith@gov.bc.ca
              firstName:
                type: string
                example: Jane
              lastName:
                type: string
                example: Smith
              attributes:
                type: object
                properties:
                  display_name:
                    type: array
                    items:
                      type: string
                      example: Jane Smith
                  idir_user_guid:
                    type: array
                    items:
                      type: string
                      example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l
                  idir_username:
                    type: array
                    items:
                      type: string
                      example: JASMITH
    CurrentUser:
      type: object
      properties:
        id:
          type: string
          description: ID of the user
          example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l
        idpUserId:
          type: string
          description: ID of the user provided by the identity provider
          example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l
        username:
          type: string
          description: Username of this user
          example: jsmith
        firstName:
          type: string
          example: Jane
        fullName:
          type: string
          example: Jane Smith
        lastName:
          type: string
          example: Smith
        email:
          type: string
          example: jsmith@gov.bc.ca
        public:
          type: boolean
          example: false
    DocumentTemplateRequest:
      type: object
      properties:
        filename:
          type: string
          description: >
            The filename that the document template had when it was originally
            uploaded.
          example: my_document_template.txt
        template:
          type: string
          description: >
            The file that is the document template to be used in document
            generation.
          example: Hello {d.firstName}
    DocumentTemplateResponse:
      allOf:
        - $ref: '#/components/schemas/DocumentTemplateResponseBasic'
        - type: object
          properties:
            template:
              type: string
              description: >
                The file that is the document template to be used in document
                generation.
              example: Hello {d.firstName}
    DocumentTemplateResponseBasic:
      allOf:
        - type: object
          properties:
            id:
              type: string
              format: uuid
              description: |
                The unique identifier for the document template.
              example: 7a61407b-2c00-467d-9dd5-f9f060779c5b
            formId:
              type: string
              format: uuid
              description: >
                The unique identifier for the form that this document template
                belongs to.
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            active:
              type: boolean
              description: >
                Whether the document template is active. Inactive templates are
                treated as if they do not exist and will not be returned by GET
                routes.
              example: true
            filename:
              type: string
              description: >
                The filename that the document template had when it was
                originally uploaded.
              example: my_document_template.docx
        - $ref: '#/components/schemas/TimeStampCreate'
    PrintConfigRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          enum:
            - default
            - direct
          description: >
            The print configuration type. `default` allows users to choose
            between browser print or template-based document generation.
            `direct` forces users to print directly using a pre-configured
            template, generating a PDF output.
          example: direct
        templateId:
          type: string
          format: uuid
          nullable: true
          description: >
            The unique identifier for the document template to use when `code`
            is `direct`. Required when `code` is `direct`, ignored when `code`
            is `default`. Must reference an active document template for the
            form.
          example: 7a61407b-2c00-467d-9dd5-f9f060779c5b
        outputFileType:
          type: string
          nullable: true
          description: >
            The output file type for document generation. Defaults to `pdf` when
            `code` is `direct`. Ignored when `code` is `default`.
          example: pdf
        reportName:
          type: string
          nullable: true
          description: >
            Custom name for the generated document file. Used when
            `reportNameOption` is set to `custom`.
          example: custom-report-name
        reportNameOption:
          type: string
          nullable: true
          enum:
            - formName
            - custom
          description: >
            Option for how to name the generated document file. `formName` uses
            the form name, `custom` uses the value from `reportName`.
          example: formName
    PrintConfigResponse:
      allOf:
        - type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
              description: |
                The unique identifier for the print configuration.
              example: 3cb9acc7-cfd8-4491-b091-1277bc0ec303
            formId:
              type: string
              format: uuid
              description: >
                The unique identifier for the form that this print configuration
                belongs to.
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            code:
              type: string
              enum:
                - default
                - direct
              description: |
                The print configuration type.
              example: direct
            templateId:
              type: string
              format: uuid
              nullable: true
              description: >
                The unique identifier for the document template used when `code`
                is `direct`. `null` when `code` is `default`.
              example: 7a61407b-2c00-467d-9dd5-f9f060779c5b
            outputFileType:
              type: string
              nullable: true
              description: >
                The output file type for document generation. Typically `pdf`
                when `code` is `direct`, `null` when `code` is `default`.
              example: pdf
            reportName:
              type: string
              nullable: true
              description: >
                Custom name for the generated document file. Used when
                `reportNameOption` is set to `custom`.
              example: custom-report-name
            reportNameOption:
              type: string
              nullable: true
              enum:
                - formName
                - custom
              description: |
                Option for how to name the generated document file.
              example: formName
        - $ref: '#/components/schemas/TimeStampUserData'
      description: >
        The print configuration for a form. Returns `null` if no print
        configuration has been set.
    EmailMessage:
      allOf:
        - type: object
          properties:
            msgid:
              type: string
              format: uuid
              description: ID of message.
              example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
            to:
              type: array
              items:
                type: string
                example: jsmith@email.com
              description: an array of the message recipients
            txId:
              type: string
              format: uuid
              description: Transaction ID returned by a messaging service
              example: 7d13b78b-21d2-4128-b4e8-02ad3da17d22
    EncryptionKey:
      allOf:
        - type: object
          properties:
            id:
              type: string
              format: uuid
              description: ID of EncryptionKey.
              example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
            formId:
              type: string
              format: uuid
              description: Form ID this EncryptionKey belongs to.
              example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
            name:
              type: string
              description: Name to identify this EncryptionKey to a user
              example: private-event-stream
            algorithm:
              type: string
              description: Algorithm used for encryption
              example: aes-256-gcm
            key:
              type: string
              format: sha256 hash
              description: sha256 hash for encryption algorithm
              example: ad5520469720325d1694c87511afda28a0432dd974cb77b5b4b9f946a5af6985
        - $ref: '#/components/schemas/TimeStampUserData'
    Error:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          properties:
            status:
              example: 500
            title:
              example: Internal Server Error
            type:
              example: https://httpstatuses.com/500
    EventStreamConfig:
      allOf:
        - type: object
          properties:
            id:
              type: string
              format: uuid
              description: ID of EventStreamConfig.
              example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
            formId:
              type: string
              format: uuid
              description: Form ID this EventStreamConfig belongs to.
              example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
            enablePublicStream:
              type: boolean
              description: When true, send messages on public stream
            enablePrivateStream:
              type: boolean
              description: >-
                When true, send messages on private stream (requires
                EncryptionKey)
            encryptionKeyId:
              type: string
              format: uuid
              description: Id of EncryptionKey for private stream
              example: 7d13b78b-21d2-4128-b4e8-02ad3da17d22
            encryptionKey:
              $ref: '#/components/schemas/EncryptionKey'
        - $ref: '#/components/schemas/TimeStampUserData'
    ExternalApi:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of ExternalApi.
          example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
        formId:
          type: string
          format: uuid
          description: Form ID this ExternalApi belongs to.
          example: 1223h78b-21d2-4128-b4e8-02ad3daipoi32
        name:
          type: string
          description: Name of the ExternalApi - unique per form.
          example: BC Registries Number Lookup
        endpointUrl:
          type: string
          format: url
          description: Endpoint URL of the External API - the api to call.
          example: https://bcreg.com/v1/lookup
        code:
          type: string
          description: Status code.
          example: APPROVED
        sendApiKey:
          type: boolean
          description: True, send an API Key to External API Endpoint
        apiKeyHeader:
          type: string
          description: Name of API Key header
          example: X-API-KEY
        apiKey:
          type: string
          description: API Key Header value
        allowSendUserToken:
          type: boolean
          description: Set by CHEFS Admin, true allows the sendUserToken to be set to true
        sendUserToken:
          type: boolean
          description: True, send the user's token in headers to External API
        userTokenHeader:
          type: string
          description: Name of header for sending the user token
        userTokenBearer:
          type: boolean
          description: When true, send user token as a Bearer token
        sendUserInfo:
          type: boolean
          description: Include user information via headers to External API
    FileUpload:
      type: object
      properties:
        createdAt:
          type: string
          example: '2020-06-04T18:49:20.672Z'
        createdBy:
          type: string
          example: jsmith@idir
        id:
          type: string
          format: uuid
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
        originalName:
          type: string
          example: hiring_approval_request_form_schema.json
        size:
          type: integer
          description: Size in bytes of the file.
          example: 27462
    Form:
      allOf:
        - $ref: '#/components/schemas/FormBasic'
        - $ref: '#/components/schemas/FormWithoutVersions'
        - type: object
          properties:
            versions:
              type: array
              items:
                $ref: '#/components/schemas/FormVersionBasic'
        - $ref: '#/components/schemas/TimeStampUserData'
    FormApiDetails:
      allOf:
        - type: object
          properties:
            id:
              type: number
              example: 4
            formId:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
        - $ref: '#/components/schemas/TimeStampUserData'
    FormApiKey:
      allOf:
        - type: object
          properties:
            id:
              type: number
              example: 4
            formId:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            secret:
              type: string
              example: dd7d1699-61ec-4237-aa33-727f8aa79c0a
            filesApiAccess:
              type: boolean
              example: true
        - $ref: '#/components/schemas/TimeStampUserData'
    FormBasic:
      allOf:
        - $ref: '#/components/schemas/FormCore'
        - type: object
          properties:
            formMetadata:
              type: object
              description: Contains Custom Form Metadata object
              properties:
                metadata:
                  type: object
                  description: JSON Object
                  example:
                    externalId: AB-0123456789
            identityProviders:
              type: array
              items:
                $ref: '#/components/schemas/IdentityProvider'
            showSubmissionConfirmation:
              type: boolean
              example: true
            sendSubmissionReceivedEmail:
              type: boolean
              example: true
              description: Used to indicate if team should be notified upon submission
            submissionReceivedEmails:
              type: array
              items:
                type: string
              example:
                - me@email.com
                - manager@email.com
            enableDocumentTemplates:
              type: boolean
              example: true
            enableStatusUpdates:
              type: boolean
              example: true
            enableSubmitterDraft:
              type: boolean
              example: true
            reminder_enabled:
              type: boolean
              example: true
              description: Allow form to send reminder email to all submitters
            schedule:
              type: object
              description: Contains schedule related data
              properties:
                enabled:
                  type: boolean
                  description: Used to indicate if schedule feature enabled or not
                  example: true
                scheduleType:
                  type: string
                  description: >-
                    Shows type of Schedule setting choose by form designed.
                    Could be period,closingDate,manual
                  example: period
                closingMessage:
                  type: string
                  description: >-
                    This string contain custom closing message message set by
                    form designer that shows on frontend when a form is expired
                    for a particular period.
                  example: This Form is expired.
                allowLateSubmissions:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: >-
                        Used to indicate if late submission allowed on a form or
                        not, Will be true if enabled
                      example: true
                    forNext:
                      type: object
                      properties:
                        term:
                          type: string
                          description: >-
                            This contain a value that can be used with
                            combination to another key i.e. intervalType to
                            calculate a period. Thats tells a form to be allowed
                            a late submission for particular period.  40 Days, 3
                            Weeks, 1 Years etc.
                        intervalType:
                          type: string
                          description: >-
                            This contain a value that can be used with
                            combination to another key i.e. term to calculate a
                            period. Thats tells a form to be allowed a late
                            submission for particular period.  40 Days, 3 Weeks,
                            1 Years etc.
                closingMessageEnabled:
                  type: boolean
                  description: Set to true when custom closing message is enabled
                  example: true
                openSubmissionDateTime:
                  type: string
                  description: Contains open date of form schedule system.
                  example: '2022-12-22'
                closeSubmissionDateTime:
                  type: string
                  description: >-
                    Contains closing date of form schedule system when type of
                    ScheduleType set to closingDate.
                  example: '2022-12-22'
                keepOpenForTerm:
                  type: string
                  description: Deprecated. Previously used for PERIOD scheduling.
                  deprecated: true
                keepOpenForInterval:
                  type: string
                  description: Deprecated. Previously used for PERIOD scheduling.
                  deprecated: true
                repeatSubmission:
                  type: object
                  description: Deprecated. Previously used for PERIOD scheduling.
                  deprecated: true
                  properties:
                    enabled:
                      type: boolean
                      description: Deprecated.
                    everyTerm:
                      type: string
                      description: Deprecated.
                    repeatUntil:
                      type: string
                      description: Deprecated.
                    everyIntervalType:
                      type: string
                      description: Deprecated.
            subscribe:
              type: object
              description: >-
                Contains subscription related data - future storage of
                subscribed events
              properties:
                enabled:
                  type: boolean
                  description: Used to indicate if subscribe feature enabled or not
                  example: true
            enableCopyExistingSubmission:
              type: boolean
              example: false
            deploymentLevel:
              type: string
              description: >-
                Indicates whether the created form is for development, test, or
                production purposes
              example: production
            ministry:
              type: string
              description: Contains the ministry the form is associated to
              example: CITZ
            apiIntegration:
              type: boolean
              description: Set to true if the form user will utilize API integration
              example: true
            useCase:
              type: string
              description: >-
                This contains a value that makes apparent that use case of the
                created form
              example: feedback
            eventStreamConfig:
              $ref: '#/components/schemas/EventStreamConfig'
    FormCore:
      type: object
      properties:
        name:
          type: string
          example: My Survey Form
        description:
          type: string
          example: I built this survey form. It is amazing.
    FormDraft:
      allOf:
        - type: object
          properties:
            id:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            formId:
              type: string
              format: uuid
              description: ID of the form
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            formVersionId:
              type: string
              format: uuid
              description: ID of the FormVersion this submission is for.
              example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
        - $ref: '#/components/schemas/FormSchema'
        - $ref: '#/components/schemas/TimeStampUserData'
    FormOptions:
      allOf:
        - $ref: '#/components/schemas/FormCore'
        - type: object
          properties:
            id:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            idpHints:
              type: array
              example:
                - idir
              items:
                type: string
            snake:
              type: string
              example: my-survey-form
    FormPreferences:
      type: object
      description: Form level user preferences
      properties:
        columnList:
          type: array
          description: A list of desired columns to show
          example:
            - foo
            - bar
          items:
            type: string
    FormRoleUser:
      type: object
      properties:
        formId:
          type: string
          format: uuid
          description: ID of form
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
        role:
          type: string
          description: code of role
          example: team_manager
        userId:
          type: string
          description: ID of user
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
    FormSchema:
      allOf:
        - type: object
          properties:
            schema:
              type: object
              description: this is the json for the form design.
              example:
                display: form
                type: form
                components:
                  - type: textfield
                    key: firstName
                    label: First Name
                    placeholder: Enter your first name.
                    input: true
                    tooltip: Enter your <strong>First Name</strong>
                    description: Enter your <strong>First Name</strong>
                  - type: textfield
                    key: lastName
                    label: Last Name
                    placeholder: Enter your last name.
                    input: true
                    tooltip: Enter your <strong>Last Name</strong>
                    description: Enter your <strong>Last Name</strong>
    FormSubmission:
      allOf:
        - $ref: '#/components/schemas/FormSubmissionBasic'
        - $ref: '#/components/schemas/FormSubmissionCore'
        - type: object
          properties:
            confirmationId:
              type: string
              description: shortend version of the id, useful for visual representation
              example: AEB3B705
            deleted:
              type: boolean
              description: Used to indicate a soft delete.
              example: false
    FormSubmissionBasic:
      allOf:
        - type: object
          properties:
            draft:
              type: boolean
              description: >-
                Used to indicate if submission came from a draft version of a
                form.
              example: false
            submission:
              type: object
              description: this is the json for the form submission.
        - $ref: '#/components/schemas/TimeStampUserData'
    FormSubmissionCore:
      type: object
      properties:
        id:
          type: string
          example: c0822716-01f5-43e6-b4d4-ffcacd13aae3
        formVersionId:
          type: string
          description: ID of the FormVersion this submission is for.
          example: b6908dd4-2f01-4e08-831d-921edae99ca3
    FormSubmissionDeleted:
      allOf:
        - $ref: '#/components/schemas/FormSubmission'
        - type: object
          properties:
            deleted:
              type: boolean
              description: Used to indicate a soft delete.
              example: true
    FormSubmissionDiscover:
      type: object
      properties:
        id:
          type: string
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
      example:
        id: aeb3b705-1de5-4f4e-a4e6-0716b7671034
        textField1: foo
        checkbox1: bar
        radioGroup1: baz
        email1: test@email.com
    FormSubmissionExport:
      allOf:
        - type: object
          properties:
            form:
              type: object
              properties:
                confirmationId:
                  type: string
                  description: shortend version of the id, useful for visual representation
                  example: AEB3B705
                formName:
                  type: string
                  description: The title of the form
                  example: My Survey Form
                username:
                  type: string
                  description: Username of this user
                  example: jsmith
                fullName:
                  type: string
                  example: Jane Smith
                email:
                  type: string
                  example: jsmith@gov.bc.ca
                version:
                  type: integer
                  description: The version number of the form for a submission
                  example: 1
                createdAt:
                  type: string
                  example: '2020-06-04T18:49:20.672Z'
                submittedAt:
                  type: string
                  description: >-
                    Represents the timestamp indicating when a submission was
                    last moved to the SUBMITTED state. If a submission is
                    revised and resubmitted multiple times, submittedAt will
                    update each time the state changes back to SUBMITTED,
                    reflecting the most recent submission time.
                  example: '2020-06-04T18:49:20.672Z'
            formFieldA:
              type: string
              description: A field in the submission object
            formFieldB:
              type: string
              description: A field in the submission object
    FormSubmissionExportWithFields:
      allOf:
        - type: object
          properties:
            format:
              type: string
              description: Chosen file type for the submission data exported
              example: csv
            template:
              type: string
              description: Chosen CSV format for the submission data exported
              example: multiRowEmptySpacesCSVExport
            version:
              type: integer
              description: The version number of the form for the submission data exported
              example: 1
            type:
              type: string
              description: default value is submissions and should be changed
              example: submissions
            preference:
              type: object
              description: form submissions export preferences
              example:
                minDate: null
                maxDate: null
            fields:
              type: array
              description: List of form submission fields to be exported to CSV
              example:
                - form.confirmationId,
                - form.formName,
                - form.version,
                - form.createdAt,
                - form.fullName,
                - form.username,
                - form.email,
                - form.status,
                - form.assignee,
                - form.assigneeEmail,
                - fishermansName,
                - email,
                - forWhichBcLakeRegionAreYouCompletingTheseQuestions,
                - didYouFishAnyBcLakesThisYear,
                - oneRowPerLake,
                - oneRowPerLake.lakeName,
                - oneRowPerLake.closestTown,
                - oneRowPerLake.numberOfDays,
                - oneRowPerLake.dataGrid,
                - oneRowPerLake.dataGrid.fishType,
                - oneRowPerLake.dataGrid.numberCaught,
                - oneRowPerLake.dataGrid.numberKept
              items:
                type: string
            emailExport:
              type: boolean
              description: >-
                This parameter should be set to true if the form submissions are
                large (e.g. above 500) or the form is big
              example: false
    FormSubmissionMultiple:
      allOf:
        - type: object
          properties:
            draft:
              type: boolean
              description: >-
                Used to indicate if submission came from a draft version of a
                form.
              example: false
            submission:
              type: object
              description: >-
                this object should contain one property named data as an array.
                This array named data should store all the multiple drafts as
                object in this array.
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/FormSubmissionObjectForMultipleUpload'
                  description: >-
                    this is an array of multiple objects, each object contain
                    data of single the form submissions.
    FormSubmissionObjectForMultipleUpload:
      allOf:
        - type: object
          description: this is the json for the form submission.
    FormSubmissionResponseMultiple:
      allOf:
        - type: array
          items:
            type: object
            properties:
              draft:
                type: boolean
                description: >-
                  Used to indicate if submission came from a draft version of a
                  form.
                example: false
              submission:
                type: object
                description: >-
                  this object should contain one property named data as an
                  array. This array named data should store all the multiple
                  drafts as object in this array.
                properties:
                  data:
                    type: array
                    items:
                      $ref: >-
                        #/components/schemas/FormSubmissionObjectForMultipleUpload
                    description: >-
                      this is an array of multiple objects, each object contain
                      data of single the form submissions.
    FormSubmissionSummary:
      allOf:
        - type: object
          properties:
            textField1:
              type: string
              example: >-
                the contents of the field called 'textField1' from the 'fields'
                query param
            submissionId:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            formId:
              type: string
              format: uuid
              description: ID of the form this submission is for.
              example: bea3b705-1de5-4f4e-a4e6-0716b7674132
            formName:
              type: string
              description: The title of the form
              example: My Survey Form
            formVersionId:
              type: string
              description: ID of the FormVersion this submission is for.
              example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
            confirmationId:
              type: string
              description: shortend version of the id, useful for visual representation
              example: AEB3B705
            deleted:
              type: boolean
              description: Used to indicate a soft delete.
              example: false
            draft:
              type: boolean
              description: >-
                Used to indicate if submission came from a draft version of a
                form.
              example: false
            version:
              type: integer
              description: The version number of the form for a submission
              example: 1
        - $ref: '#/components/schemas/TimeStampUserData'
    FormUserList:
      allOf:
        - type: object
          properties:
            id:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            name:
              type: string
              example: My Survey Form.
            users:
              type: array
              items:
                $ref: '#/components/schemas/UserFormBasic'
    FormVersion:
      allOf:
        - $ref: '#/components/schemas/FormVersionBasic'
        - $ref: '#/components/schemas/FormSchema'
    FormVersionBasic:
      allOf:
        - $ref: '#/components/schemas/FormVersionCore'
        - type: object
          properties:
            version:
              type: integer
              example: 1
            published:
              type: boolean
              example: true
        - $ref: '#/components/schemas/TimeStampUserData'
    FormVersionCore:
      type: object
      properties:
        id:
          type: string
          example: b6908dd4-2f01-4e08-831d-921edae99ca3
        formId:
          type: string
          format: uuid
          description: ID of the form
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
    FormVersionFields:
      type: array
      example:
        - textField1
        - checkbox1
        - radioGroup1
        - email1
      items:
        type: string
    FormWithoutVersions:
      allOf:
        - $ref: '#/components/schemas/FormBasic'
        - type: object
          properties:
            id:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            active:
              type: boolean
              example: true
            labels:
              type: array
              example:
                - Survey
              items:
                type: string
            snake:
              type: string
              example: my-survey-form
        - $ref: '#/components/schemas/TimeStampUserData'
    IdentityProvider:
      allOf:
        - type: object
          properties:
            code:
              type: string
              example: idir
            display:
              type: string
              example: IDIR
            idp:
              type: string
              description: >-
                The identity_provider a user logs in with.  Allows us to
                determine what source authenticated the user.
              example: idir
            active:
              type: boolean
              example: true
        - $ref: '#/components/schemas/TimeStampUserData'
    Label:
      type: array
      example:
        - Survey
        - Questionnaire
        - Feedback
      items:
        type: string
    Note:
      type: object
      properties:
        submissionId:
          type: string
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
        submissionStatusId:
          type: string
          example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
        note:
          type: string
          example: >-
            'This is a note that can be up to 4000 characters I add to the
            submission and can link to an individual status id'
    EmailRecipients:
      type: object
      properties:
        emailRecipients:
          type: array
          items:
            type: string
          example:
            - xyz@email.com
            - abc@email.com
    Permission:
      allOf:
        - $ref: '#/components/schemas/PermissionBasic'
        - type: object
          properties:
            roles:
              type: array
              items:
                $ref: '#/components/schemas/RoleBasic'
    PermissionBasic:
      allOf:
        - type: object
          properties:
            code:
              type: string
              example: design_update
            display:
              type: string
              description: The permission name
              example: Design Update
            description:
              type: string
              example: Can edit/update the form design
            active:
              type: boolean
              example: true
        - $ref: '#/components/schemas/TimeStampUserData'
    Problem:
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          description: What type of problem, link to explanation of problem
        title:
          type: string
          description: Title of problem, generally the HTTP status code description
        status:
          type: string
          description: The HTTP status code
        detail:
          type: string
          description: Short description of why this problem was raised
    ProxyData:
      properties:
        X-CHEFS-PROXY-DATA:
          type: string
          description: >-
            Encrypted payload that includes user identification and
            form/submission identification. Can only be read by CHEFs server.
    ProxyInfo:
      properties:
        formId:
          type: string
          description: Id of the form (required when no submissionId)
        versionId:
          type: string
          description: Id of the form version (required when no submissionId)
        submissionId:
          type: string
          description: >-
            Id of the submission (optional) if submissionId provided, then
            formId and versionId are ignored
    Role:
      allOf:
        - $ref: '#/components/schemas/RoleBasic'
        - type: object
          properties:
            permissions:
              type: array
              items:
                $ref: '#/components/schemas/PermissionBasic'
    RoleBasic:
      allOf:
        - type: object
          properties:
            code:
              type: string
              example: form_designer
            display:
              type: string
              description: The role name
              example: Form Designer
            description:
              type: string
              example: Designs the form
            active:
              type: boolean
              example: true
        - $ref: '#/components/schemas/TimeStampUserData'
    StatusCodes:
      allOf:
        - type: object
          properties:
            id:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            formId:
              type: string
              example: ccb5b715-1de5-4f4e-a4e6-0716b7671034
            code:
              type: string
              example: COMPLETED
            statusCode:
              type: object
              properties:
                code:
                  type: string
                  example: COMPLETED
                display:
                  type: string
                  example: Completed
                nextCodes:
                  type: array
                  example:
                    - ASSIGNED
                    - COMPLETED
                  items:
                    type: string
        - $ref: '#/components/schemas/TimeStampUserData'
    ServiceStatus:
      type: object
      properties:
        ready:
          type: boolean
          description: If CHEFS is ready to accept requests
          example: true
        stopped:
          type: boolean
          description: If CHEFS is stopped or in the process of shutting down
          example: false
        connections:
          type: object
          description: Describe state of services CHEFS requires
          properties:
            clamAvScanner:
              type: object
              properties:
                displayName:
                  type: string
                  description: Name of the service
                  example: Virus Scanner
                connected:
                  type: boolean
                  description: >-
                    Indicate if CHEFS is currently able to connect to the
                    service
                  example: true
                started:
                  type: boolean
                  description: >-
                    Indicate if CHEFS initialized the connection to the service
                    at startup
                  example: true
            dataConnection:
              type: object
              properties:
                displayName:
                  type: string
                  description: Name of the service
                  example: Data Connection
                connected:
                  type: boolean
                  description: >-
                    Indicate if CHEFS is currently able to connect to the
                    service
                  example: true
                started:
                  type: boolean
                  description: >-
                    Indicate if CHEFS initialized the connection to the service
                    at startup
                  example: true
            eventStreamService:
              type: object
              properties:
                displayName:
                  type: string
                  description: Name of the service
                  example: Event Stream Service
                connected:
                  type: boolean
                  description: >-
                    Indicate if CHEFS is currently able to connect to the
                    service
                  example: true
                started:
                  type: boolean
                  description: >-
                    Indicate if CHEFS initialized the connection to the service
                    at startup
                  example: true
    SubmissionEditMetadata:
      type: object
      properties:
        id:
          type: integer
          example: 5
        updatedByUsername:
          type: string
          example: jsmith
        actionTimestamp:
          type: string
          example: '2020-06-04T18:49:20.672Z'
        action:
          type: string
          example: U
    SubmissionFormVersion:
      type: object
      properties:
        submission:
          $ref: '#/components/schemas/FormSubmission'
        version:
          $ref: '#/components/schemas/FormVersion'
        form:
          $ref: '#/components/schemas/Form'
    SubmissionFormVersionDeleted:
      type: object
      properties:
        submission:
          $ref: '#/components/schemas/FormSubmissionDeleted'
        version:
          $ref: '#/components/schemas/FormVersion'
        form:
          $ref: '#/components/schemas/FormWithoutVersions'
    SubmissionFormVersionOptions:
      type: object
      properties:
        submission:
          $ref: '#/components/schemas/FormSubmissionCore'
        version:
          $ref: '#/components/schemas/FormVersionCore'
        form:
          $ref: '#/components/schemas/FormOptions'
    SubmissionStatus:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: >-
            Status code to assign. Check the `/forms/{formId}/statusCodes`
            endpoint for valid

            codes.
          example: ASSIGNED
        assignedToUserId:
          type: string
          description: >-
            Optional UserID assignment. Only applicable when `code` is
            `ASSIGNED`.
          example: ccb5b715-1de5-4f4e-a4e6-0716b7671034
        assignmentNotificationEmail:
          type: string
          description: >-
            Optional email for dispatching assignment notifications. If this
            property is falsy, no notification will be sent.
          example: jsmith@gov.bc.ca
        actionDate:
          type: string
          description: >-
            Optional time this status comes into effect. Defaults to now if
            unspecified.
          example: '2020-06-04T18:49:20.672Z'
        submissionUserEmail:
          type: string
          description: >-
            Optional email address for dispatching an email notification to the
            submitter. If this property is falsy, no notification will be sent.
          example: bsmith@gov.bc.ca
        revisionNotificationEmailContent:
          type: string
          description: >-
            Optional revision request email content. This plaintext string will
            be added to the revision requests email body contents.
          example: foo bar
    SubmissionStatusHistory:
      allOf:
        - type: object
          properties:
            id:
              type: string
              example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
            submissionId:
              type: string
              example: ccb5b715-1de5-4f4e-a4e6-0716b7671034
            code:
              type: string
              example: COMPLETED
            assignedToUserId:
              type: string
              example: dda7a123-1de5-4f4e-a4e6-0716b7671034
            actionDate:
              type: string
              example: '2020-06-04T18:49:20.672Z'
            user:
              $ref: '#/components/schemas/User'
        - $ref: '#/components/schemas/TimeStampUserData'
    TemplateRenderObject:
      type: object
      properties:
        options:
          type: object
          description: Object containing processing options
          properties:
            convertTo:
              type: string
              description: >-
                The desired file type of the generated document. If not
                supplied, will use the original contentFileType.
              example: pdf
            reportName:
              type: string
              description: >-
                The desired file name of the generated document. Can perform
                template substitution using the form data. If not supplied, will
                use a random UUID.
              example: abc_123_{d.firstName}_{d.lastName}.pdf
        template:
          type: object
          description: Object containing the document template
          properties:
            content:
              type: string
              description: >-
                The document template encoded as a `base64` string. The example
                is the encoded value of the text file `Hello {d.firstName}
                {d.lastName}!`.
              example: SGVsbG8ge2QuZmlyc3ROYW1lfSB7ZC5sYXN0TmFtZX0hCg==
            encodingType:
              type: string
              description: 'The encoding of the `content` property: use `base64`.'
              example: base64
            fileType:
              type: string
              description: The original file type of the `content` document template.
              example: txt
    TimeStampCreate:
      type: object
      properties:
        createdBy:
          type: string
          description: |
            The username of the person who created the object.
          example: bsmith@idir
        createdAt:
          type: string
          description: |
            The UTC date and time when the object was created.
          example: '2020-06-04T18:49:20.672Z'
        updatedBy:
          type: string
          description: |
            The username of the person who last modified the object.
          example: null
        updatedAt:
          type: string
          description: |
            The UTC date and time when the object was last modified.
          example: '2020-06-04T18:49:20.672Z'
    TimeStampUserData:
      type: object
      properties:
        createdBy:
          type: string
          description: |
            The username of the person who created the object.
          example: bsmith@idir
        createdAt:
          type: string
          description: |
            The UTC date and time when the object was created.
          example: '2020-06-04T18:49:20.672Z'
        updatedBy:
          type: string
          description: |
            The username of the person who last modified the object.
          example: jsmith@idir
        updatedAt:
          type: string
          description: |
            The UTC date and time when the object was last modified.
          example: '2020-06-05T11:27:15.853Z'
    User:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: ID of the user
              example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
            idpUserId:
              type: string
              description: ID of the user in the external identity provider system
              example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l
            username:
              type: string
              description: Username of this user
              example: jsmith
            firstName:
              type: string
              example: Jane
            fullName:
              type: string
              example: Jane Smith
            lastName:
              type: string
              example: Smith
            email:
              type: string
              example: jsmith@gov.bc.ca
            idpCode:
              type: string
              example: idir
        - $ref: '#/components/schemas/TimeStampUserData'
    UserAccess:
      type: object
      properties:
        userId:
          type: string
          description: ID of the user
          example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        idpUserId:
          type: string
          description: ID of the user in the external identity provider system
          example: ao9rsqw60nvf24pemkdik5e3fmo2kb6l
        username:
          type: string
          description: Username of this user
          example: jsmith
        firstName:
          type: string
          example: Jane
        fullName:
          type: string
          example: Jane Smith
        lastName:
          type: string
          example: Smith
        email:
          type: string
          example: jsmith@gov.bc.ca
        formId:
          type: string
          format: uuid
          description: ID of the form
          example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        formName:
          type: string
          example: jsmith@gov.bc.ca
        labels:
          type: array
          example:
            - Survey
          items:
            type: string
        active:
          type: boolean
          example: true
        identityProviders:
          type: array
          description: the Identity Provider code associated with this form
          example:
            - bceid
            - idir
          items:
            type: string
        idps:
          type: array
          description: the Identity Provider idps associated with this form
          example:
            - bceid
            - idir
          items:
            type: string
        formVersionId:
          type: string
          description: ID of the current form version
          example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
        version:
          type: integer
          description: Number of the current form version
          example: 1
        published:
          type: boolean
          example: true
        versionUpdatedAt:
          type: string
          description: when latest form version was last updated
          example: '2020-06-04T18:49:20.672Z'
        roles:
          type: array
          description: the role codes this user has on this form
          example:
            - owner
            - team_manager
          items:
            type: string
        permissions:
          type: array
          description: the permission codes this user has on this form
          example:
            - design_update
            - submission_create
          items:
            type: string
    UserAccessSubmission:
      type: object
      properties:
        active:
          type: boolean
          example: true
        confirmationId:
          type: string
          example: 5DAD1EC9
        createdAt:
          type: string
          example: '2020-06-04T18:49:20.672Z'
        description:
          type: string
          example: A BC Hunting licence application
        draft:
          type: boolean
          example: true
        enableStatusUpdates:
          type: boolean
          example: true
        enableSubmitterDraft:
          type: boolean
          example: true
        formId:
          type: string
          example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        formSubmissionId:
          type: string
          example: 6dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        name:
          type: string
          example: Licence Application
        permissions:
          type: array
          description: the permission codes this user has on this form
          example:
            - submission_delete
            - submission_create
          items:
            type: string
        user:
          $ref: '#/components/schemas/User'
        userId:
          type: string
          example: 7dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
    UserForm:
      type: object
      properties:
        formId:
          type: string
          format: uuid
          description: ID of the form
          example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        formName:
          type: string
          example: jsmith@gov.bc.ca
        labels:
          type: array
          example:
            - Form
          items:
            type: string
        idps:
          type: array
          description: the Identity Provider code associated with this form
          example:
            - bceid
            - idir
          items:
            type: string
        active:
          type: boolean
          example: true
        formVersionId:
          type: string
          description: ID of the current form version
          example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
        version:
          type: integer
          description: Number of the current form version
          example: 1
        roles:
          type: array
          description: the role codes this user has on this form
          example:
            - owner
            - team_manager
          items:
            type: string
        permissions:
          type: array
          description: the permission codes this user has on this form
          example:
            - design_update
            - submission_create
          items:
            type: string
    UserFormBasic:
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: ID of the user
          example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        username:
          type: string
          example: jsmith
        roles:
          type: array
          description: the role codes this user has on this form
          example:
            - owner
            - team_manager
          items:
            type: string
    UserFormPreferences:
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: ID of the user
          example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
        formId:
          type: string
          format: uuid
          description: ID of the form
          example: a675ab2a-1e88-4fb5-88f9-c7cb051a18b2
        preferences:
          $ref: '#/components/schemas/FormPreferences'
    UserPreferences:
      type: object
      properties:
        forms:
          type: array
          description: A list of form specific preferences
          items:
            $ref: '#/components/schemas/UserFormPreferences'
        preferences:
          type: object
          description: CHEFS app level user preferences
          example: {}
    UserSubmission:
      type: object
      properties:
        active:
          type: boolean
          description: If the submission is active
          example: true
        confirmationId:
          type: string
          description: The submission's Confirmation ID
          example: B6F3E0EB
        createdAt:
          type: string
          example: '2020-06-04T18:49:20.672Z'
        description:
          type: string
          description: The form description
          example: A form that allows a user to fill out a survey
        enableStatusUpdates:
          type: boolean
          description: If the form uses status flow
          example: true
        enableSubmitterDraft:
          type: boolean
          description: If the form's submissions can be saved as draft
          example: true
        formId:
          type: string
          format: uuid
          description: ID of the form
          example: d9249b52-d97c-4d28-90e3-a39a94c847ea
        formSubmissionId:
          type: string
          format: uuid
          description: ID of the submission
          example: b6f3e0eb-52e5-4c02-833e-d514e4610d1f
        name:
          type: string
          description: The form name
          example: NR survey form
        permissions:
          type: array
          description: the permission codes this user has on this submission
          example:
            - submission_create
            - submission_read
            - submission_delete
            - submission_update
            - submission_review
          items:
            type: string
        submissionStatus:
          type: array
          description: the permission codes this user has on this submission
          items:
            $ref: '#/components/schemas/SubmissionStatus'
        userId:
          type: string
          format: uuid
          description: ID of the user
          example: b6f3e0eb-52e5-4c02-833e-d514e4610d1f
        version:
          type: integer
          description: The version number of the form for a submission
          example: 1
  responses:
    Accepted:
      description: Accepted
    ApiNotApproved:
      description: CHEFS Admins have not approved the External API
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 407
                  title:
                    example: Proxy Authentication Required
                  type:
                    example: https://httpstatuses.com/407
    BadGateway:
      description: Error attempting to call external system
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 502
                  title:
                    example: Bad Gateway
                  type:
                    example: https://httpstatuses.com/502
    BadRequest:
      description: Request is missing content or is malformed
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 400
                  title:
                    example: Bad Request
                  type:
                    example: https://httpstatuses.com/400
    Conflict:
      description: >-
        The request conflicts with the current state of the resource. For
        example, attempting to delete a document template that is in use by a
        print configuration.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 409
                  title:
                    example: Conflict
                  type:
                    example: https://httpstatuses.com/409
    Forbidden:
      description: Lack required role to perform action
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 403
                  title:
                    example: Forbidden
                  type:
                    example: https://httpstatuses.com/403
    NoContent:
      description: Accepted and no content
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 404
                  title:
                    example: Not Found
                  type:
                    example: https://httpstatuses.com/404
    ServiceUnavailable:
      description: External service is unavailable
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  detail:
                    $ref: '#/components/schemas/ServiceStatus'
              - type: object
                properties:
                  status:
                    example: 503
                  title:
                    example: Service Unavailable
                  type:
                    example: https://httpstatuses.com/503
    TooManyRequests:
      description: BasicAuth request exceeds rate limiting
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        retry-after:
          $ref: '#/components/headers/retry-after'
    Unauthorized:
      description: Invalid authorization credentials
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  status:
                    example: 401
                  title:
                    example: Unauthorized
                  type:
                    example: https://httpstatuses.com/401
    UnprocessableEntity:
      description: >-
        The server was unable to process the contained instructions. Generally
        validation error(s).
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                required:
                  - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                        - message
                      properties:
                        value:
                          type: object
                          description: Contents of the field that was in error.
                          example: utf-8x
                        message:
                          type: string
                          description: The error message for the field.
                          example: Invalid value `encoding`.
                  status:
                    example: 422
                  title:
                    example: Unprocessable Entity
                  type:
                    example: https://httpstatuses.com/422
