---
openapi: 3.0.3
info:
  title: Collibra Data Class Importer API
  description: |
    This API provides the ability to import data classes.
  x-audience: public
  version: 0.0.1
servers:
- url: /rest/dataClassImport/v1
security:
- basicAuth: []
- jwtAuth: []
tags:
- name: OOTB Data Class
  description: Management of `Out-of-the-box Data Classes`
paths:
  /ootbDataClasses:
    get:
      tags:
      - OOTB Data Class
      summary: Find Out-Of-The-Box Data Classes
      description: |
        Returns `Out-of-the-box Data Classes` with their import status.
      operationId: findOotbDataClasses
      parameters:
      - $ref: "#/components/parameters/Offset"
      - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: |
            `OOTB Data Class` retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OotbDataClassPagedResponse"
              examples:
                no-results:
                  summary: We couldn't find any OOTB data classes
                  value:
                    results: []
                results-with-single-ootb-data-class:
                  $ref: "#/components/examples/SingleOotbDataClassAsResults"
                results-with-multiple-ootb-data-classes:
                  $ref: "#/components/examples/MultipleOotbDataClassesAsResults"
        "400":
          description: |
            Invalid request to find `OOTB Data Classes`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
              examples:
                standard-invalid-request:
                  $ref: "#/components/examples/DefaultInvalidRequest"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        "403":
          $ref: "#/components/responses/InvalidRequest403"
        "500":
          $ref: "#/components/responses/InvalidRequest500"
      security:
      - basicAuth: []
      - jwtAuth: []
  /ootbDataClasses/import:
    post:
      summary: Import OOTB Data Classes
      description: |
        It allows to import one or more OOTB data classes by their names.
        Requests to import OOTB Data Classes are transactional in nature hence either they are all
        imported successfully or an error response will be returned
      operationId: importOotbDataClasses
      tags:
      - OOTB Data Class
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportOotbDataClassesRequest"
            examples:
              import-ootb-data-classes:
                $ref: "#/components/examples/ImportThreeOotbDataClasses"
              invalid-import-request:
                summary: Invalid request. Request with empty names is not allowed.
                value:
                  dataClassNames: []
      responses:
        "204":
          description: |
            OOTB Data Classes successfully imported.
        "400":
          description: |
            Invalid request to import OOTB Data Classes
        "409":
          description: |
            One or more data classes sent to import where modified in the meanwhile by another user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
              examples:
                standard-invalid-request:
                  $ref: "#/components/examples/DefaultInvalidRequest"
                empty-ootbNames-invalid-request:
                  $ref: "#/components/examples/EmptyOotbNamesInvalidRequest"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        "403":
          $ref: "#/components/responses/InvalidRequest403"
        "500":
          $ref: "#/components/responses/InvalidRequest500"
      security:
      - basicAuth: []
      - jwtAuth: []
components:
  parameters:
    Offset:
      name: offset
      in: query
      required: false
      description: |
        The index of the first result to retrieve.

        If not set (offset = `0`), results will be retrieved starting from row `0`.
      schema:
        type: integer
        format: int32
        default: 0
    Limit:
      name: limit
      in: query
      required: false
      description: |
        The maximum number of results to retrieve.

        If not set, the default limit  (limit = `50`) will be used. The maximum value for this parameter is
        `1000`.
      schema:
        type: integer
        format: int32
        default: 50
        maximum: 1000
  schemas:
    ImportOotbDataClassesRequest:
      type: object
      description: |
        Request to import one or more `OOTB Data Classes`. `ootbNames` is mandatory and cannot be empty
      required:
      - dataClassNames
      properties:
        dataClassNames:
          $ref: "#/components/schemas/dataClassNames"
    OotbDataClassPagedResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          description: List of OOTB Data Classes paginated
          items:
            $ref: "#/components/schemas/OotbDataClass"
    dataClassNames:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 1000
      description: |
        Names of the Data Classes to import
      example:
      - SSN
      - Country
    OotbDataClass:
      type: object
      required:
      - name
      - status
      - types
      - rules
      properties:
        name:
          type: string
          description: The name of OOTB Data Class
          example: SSN
        status:
          type: string
          description: |
            The import status of OOTB Data Class.

            Values can be:
            - `NEW`
            - `EXISTS`
            - `EXISTS-DIFFERENT`
          example: EXISTS
        types:
          type: array
          items:
            type: string
          description: |
            Types of rules currently associated to the OOTB Data Class if any
          example:
          - REGULAR_EXPRESSION
          - DATA_TYPE
          - LIST_OF_VALUES
        rules:
          $ref: "#/components/schemas/ClassificationRules"
    ClassificationRules:
      type: array
      description: |
        `Classification Rules` defined for the OOTB Data Class.
      items:
        $ref: "#/components/schemas/ClassificationRule"
    ClassificationRule:
      description: |
        A `ClassificationRule` defines a representation of a rule.
      oneOf:
      - $ref: "#/components/schemas/RegularExpressionBasedClassificationRule"
      - $ref: "#/components/schemas/DataTypeBasedClassificationRule"
      - $ref: "#/components/schemas/ListOfValuesBasedClassificationRule"
      discriminator:
        propertyName: type
        mapping:
          REGULAR_EXPRESSION: "#/components/schemas/RegularExpressionBasedClassificationRule"
          DATA_TYPE: "#/components/schemas/DataTypeBasedClassificationRule"
          LIST_OF_VALUES: "#/components/schemas/ListOfValuesBasedClassificationRule"
    ListOfValuesBasedClassificationRule:
      description: |
        `Classification Rule` based on a `List Of Values` defined inline as an array of values.
      allOf:
      - $ref: "#/components/schemas/BaseClassificationRule"
      - $ref: "#/components/schemas/BaseListOfValuesBasedClassificationRule"
    RegularExpressionBasedClassificationRule:
      allOf:
      - $ref: "#/components/schemas/BaseClassificationRule"
      - $ref: "#/components/schemas/BaseRegularExpressionBasedClassificationRule"
    DataTypeBasedClassificationRule:
      allOf:
      - $ref: "#/components/schemas/BaseClassificationRule"
      - $ref: "#/components/schemas/BaseDataTypeBasedClassificationRule"
    BaseClassificationRule:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          example: REGULAR_EXPRESSION
          description: |
            RuleType used by the rule.

            The following values are currently supported:
              - `REGULAR_EXPRESSION`
              - `DATA_TYPE`
              - `LIST_OF_VALUES`
    BaseListOfValuesBasedClassificationRule:
      type: object
      properties:
        values:
          type: array
          items:
            type: string
          description: |
            Values defined as an array of strings.
          example:
          - BE
          - FR
          - NL
    BaseRegularExpressionBasedClassificationRule:
      type: object
      properties:
        regularExpression:
          type: string
          description: |
            A regular expression.
          example: "/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*$/."
    BaseDataTypeBasedClassificationRule:
      type: object
      properties:
        dataTypes:
          type: array
          description: The list of data types defining this rule.
          items:
            $ref: "#/components/schemas/DataType"
    DataType:
      type: string
      description: |
        A data type.
      example:
      - string
      - double
      - int
      - boolean
      - date
      - timestamp
    StandardErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          description: An HTTP response code.
          example: 400
        titleMessage:
          type: string
          description: A translated message.
          example: Invalid request
        helpMessage:
          type: string
          description: A translated message.
          example: Do this or do that
        userMessage:
          type: string
          description: A translated message.
          example: This has happened.
        errorCode:
          type: string
          description: An error code. This error code is not translated.
          example: dataClassWithSameNameAlreadyExists
  examples:
    DefaultInvalidRequest:
      summary: Default invalid request
      value:
        statusCode: 400
        titleMessage: Invalid Request
        helpMessage: Check the application logs for more information.
        userMessage: The request is not valid.
        errorCode: invalidRequest
    ImportThreeOotbDataClasses:
      summary: Import three OOTB Data Classes
      value:
        dataClassNames:
        - SSN
        - IBAN
        - Country
    EmptyOotbNamesInvalidRequest:
      summary: Request with empty OOTB Data Class names is invalid
      value:
        statusCode: 400
        titleMessage: OOTB Data Class names cannot be empty
        helpMessage: Request contains no OOTB Data Classes. At least one OOTB Data
          Class name needs to be provided for import
        userMessage: The request contains no OOTB Data Classes to import
        errorCode: invalidRequest
    SingleOotbDataClassAsResults:
      summary: Only a single OOTB Data Class is returned.
      value:
        results:
        - name: SSN
          types:
          - REGULAR_EXPRESSION
          status: EXISTS
          rules:
          - type: REGULAR_EXPRESSION
            regularExpression: "/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\\
              .[a-zA-Z0-9-]+)*$/."
    MultipleOotbDataClassesAsResults:
      summary: Multiple OOTB Data Classes are returned
      value:
        results:
        - name: SSN
          types:
          - REGULAR_EXPRESSION
          status: EXISTS
          rules:
          - type: REGULAR_EXPRESSION
            regularExpression: "/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\\
              .[a-zA-Z0-9-]+)*$/."
        - name: IBAN
          types:
          - REGULAR_EXPRESSION
          - LIST_OF_VALUES
          status: NEW
          rules:
          - type: REGULAR_EXPRESSION
            regularExpression: "/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\\
              .[a-zA-Z0-9-]+)*$/."
          - type: LIST_OF_VALUES
            values:
            - IT
            - BE
            - FR
  responses:
    InvalidRequest400:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 400
            titleMessage: Invalid Request
            helpMessage: Please check the application logs for more information.
            userMessage: The request is not valid.
            errorCode: invalidRequest
    InvalidRequest500:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 500
            titleMessage: Unexpected error
            helpMessage: Please check the application logs for more information.
            userMessage: Something went wrong.
            errorCode: unexpectedError
    InvalidRequest401:
      description: The client is not authenticated.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 401
            titleMessage: Unauthorized
            helpMessage: Please check the application logs for more information.
            userMessage: Failed to authenticate request through basic credentials
            errorCode: authenticationFailed
    InvalidRequest403:
      description: The user lacks permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 403
            titleMessage: Forbidden
            helpMessage: Please check the application logs for more information.
            userMessage: The user does not have the required permissions.
            errorCode: authorizationFailed
    InvalidRequest404:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 404
            titleMessage: Not Found
            helpMessage: Please check the application logs for more information.
            userMessage: The resource could not be found
            errorCode: Not found
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Collibra REST API authentication using Basic Authentication.
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Collibra REST API authentication using JSON Web Token.
