common.yml

openapi: 3.0.4
components:
  parameters:
    x-request:
      in: header
      name: X-RequestID
      schema:
        type: string
        description: It allows the client and server to correlate each HTTP request. HTTP requests with an identifier are sent from the client to the server and back again.

  schemas:
    PageIndex:
      title: "PageIndex"
      description: "Page index of the image from input list"
      type: integer

    Source:
      title: "Source"
      description: "Document data sources"
      type: string
      enum:
        - "MRZ"
        - "VISUAL"
        - "BARCODE"
        - "RFID"
        - "MAGNETIC"
        - "EXTERNAL"
        - "LIVE"
        - "FINGERPRINT"
      x-enum-varnames:
        - "MRZ"
        - "VISUAL"
        - "BARCODE"
        - "RFID"
        - "MAGNETIC"
        - "EXTERNAL"
        - "LIVE"
        - "FINGERPRINT"
      x-enum-descriptions:
        - "Machine readable zone (MRZ)"
        - "Visual zone"
        - "Barcode"
        - "RFID"
        - "Magnetic"
        - "External"
        - "Live"
        - "Fingerprint"

    CheckResult:
      title: "CheckResult"
      type: integer
      description: "0 - result is negative; 1 - result is positive; 2 - сheck was not performed"
      enum:
        - 0
        - 1
        - 2
      x-enum-varnames:
        - "ERROR"
        - "OK"
        - "WAS_NOT_DONE"
      x-enum-descriptions:
        - "Check was performed and result is NEGATIVE"
        - "Check was performed and result is POSITIVE"
        - "Check was NOT PERFORMED"

    Scenario:
      title: "Scenario"
      type: string
      description: "Document processing scenario"
      enum:
        - "Mrz"
        - "Barcode"
        - "Locate"
        - "Ocr"
        - "DocType"
        - "MrzOrBarcode"
        - "MrzOrLocate"
        - "MrzAndLocate"
        - "BarcodeAndLocate"
        - "MrzOrOcr"
        - "MrzOrBarcodeOrOcr"
        - "LocateVisual_And_MrzOrOcr"
        - "FullProcess"
        - "FullAuth"
        - "RusStamp"
        - "OcrFree"
        - "CreditCard"
        - "Capture"
        - "DTC"
        - "RFID"
        - "mDL"
      x-enum-varnames:
        - "MRZ"
        - "BARCODE"
        - "LOCATE"
        - "OCR"
        - "DOCTYPE"
        - "MRZ_OR_BARCODE"
        - "MRZ_OR_LOCATE"
        - "MRZ_AND_LOCATE"
        - "BARCODE_AND_LOCATE"
        - "MRZ_OR_OCR"
        - "MRZ_OR_BARCODE_OR_OCR"
        - "LOCATE_VISUAL_AND_MRZ_OR_OCR"
        - "FULL_PROCESS"
        - "FULL_AUTH"
        - "RUS_STAMP"
        - "OCR_FREE"
        - "CREDIT_CARD"
        - "CAPTURE"
        - "DTC"
        - "RFID"
        - "MDL"
      x-enum-descriptions:
        - "Scenario for obtaining MRZ data"
        - "Scenario for obtaining barcode data"
        - "Scenario for detecting document boundaries"
        - "Scenario for obtaining visual zone OCR results"
        - "Scenario for document type recognition"
        - "Scenario for obtaining MRZ and/or barcode data"
        - "Scenario for detecting document boundaries and/or obtaining MRZ data"
        - "Scenario for detecting document boundaries and obtaining MRZ data"
        - "Scenario for detecting the document boundaries and obtaining barcode data"
        - "Scenario for obtaining MRZ data or visual zone OCR results"
        - "Scenario for obtaining MRZ or barcode or visual zone OCR results"
        - "Scenario for detecting document boundaries and obtaining MRZ data or visual zone OCR results"
        - "Scenario for obtaining all document data"
        - "Scenario for obtaining all document data and document authentication"
        - "Scenario for obtaining data from registration stamps"
        - "Scenario for obtaining OCR results of any image"
        - "Scenario for obtaining bank card data"
        - "Scenario for obtaining an original image without any processing"
        - "Scenario for Digital Travel Credentials (DTC-VC) data processing"
        - "Scenario for RFID chip processing"
        - "Scenario for mDL processing"

    ImageData:
      title: "ImageData"
      type: object
      properties:
        image:
          $ref: "#/components/schemas/ImageBase64"
        format:
          description: "Image format"
          type: string

    ImageTransactionData:
      title: "ImageTransactionData"
      type: object
      properties:
        image:
          $ref: './rt-images.yml#/components/schemas/ImagesFieldValue'

    ImageBase64:
      title: "ImageBase64"
      description: "Base64 encoded image"
      type: string
      format: base64
      example: "Base64 encoded image"

    RectangleCoordinates:
      title: "RectangleCoordinates"
      description: "Coordinates of the rectangle region on a document image(result type 1). Represented by two points - (left, top) + (right, bottom)"
      type: object
      required:
        - left
        - top
        - right
        - bottom
      properties:
        left:
          type: integer
        top:
          type: integer
        right:
          type: integer
        bottom:
          type: integer

    RfidLocation:
      title: "RfidLocation"
      type: integer
      description: "Determines the presence and location of an RFID chip in a document. 0 - no rfid chip; 1 - chip is located in the document data page; 2 - chip is located in the back page or inlay of the document"
      enum:
        - 0
        - 1
        - 2
      x-enum-descriptions:
        - "There is no RFID chip in the document"
        - "The RFID chip is located in the document data page"
        - "The RFID chip is located in the back page or inlay of the document"
      x-enum-varnames:
        - "NONE"
        - "MAIN_PAGE"
        - "BACK_PAGE"

    RfidOrigin:
      title: "RfidOrigin"
      type: object
      description: "Location of data in RFID chip"
      required:
        - dg
        - dgTag
        - tagEntry
        - entryView
      properties:
        dg:
          description: "Source data group file"
          type: integer
        dgTag:
          description: "Index of the source record of the image with biometric information in the information data group"
          type: integer
        tagEntry:
          description: "Index of the template in the record with biometric data"
          type: integer
        entryView:
          description: "Index of the variant of the biometric data template"
          type: integer

    Light:
      type: integer
      description: "Image light index"
      enum:
        - 0
        - 2
        - 4
        - 6
        - 24
        - 32
        - 64
        - 128
        - 134
        - 256
        - 3072
        - 4096
        - 8192
        - 65536
        - 524288
        - 1048576
        - 2097152
        - 4194304
        - 67108864
        - 268435456
        - 1073741830
        - 1073741848
        - 1073741952
      x-enum-descriptions:
        - "No Light"
        - "Upper/lower white"
        - "Side white"
        - "White"
        - "Infrared"
        - "Transmitted"
        - "Transmitted IR"
        - "Ultraviolet"
        - "White UV"
        - "IR luminescence"
        - "Axial white"
        - "IR720"
        - "IR940"
        - "Transmitted AntiStokes"
        - "UVС 254 (mod. 88X0)"
        - "UVB 313 (mod. 88X0)"
        - "White oblique light"
        - "For internal use"
        - "OVD light for hologram visualization"
        - "Light IR 870 oblique"
        - "HR white"
        - "HR IR"
        - "HR UV"
      x-enum-varnames:
        - "OFF"
        - "WHITE_TOP"
        - "WHITE_SIDE"
        - "WHITE"
        - "IR"
        - "TRANSMITTED"
        - "TRANSMITTED_IR"
        - "UV"
        - "WHITE_UV"
        - "IR_LUMINESCENCE"
        - "AXIAL_WHITE"
        - "IR_720"
        - "IR_940"
        - "ANTI_STOKES"
        - "UVC"
        - "UVB"
        - "WHITE_OBL"
        - "WHITE_SPECIAL"
        - "OVD"
        - "IR_870_OBL"
        - "HR_WHITE"
        - "HR_IR"
        - "HR_UV"

    Point:
      title: "Point"
      type: object
      required:
        - x
        - y
      properties:
        x:
          type: integer
        y:
          type: integer

    License:
      title: "License"
      description: "Base64 encoded data"
      type: string
      format: byte
      example: "Base64 encoded data"

    EncryptedRCL:
      title: "EncryptedRCL"
      description: "Base64 encoded data"
      type: string
      format: byte
      example: "Base64 encoded data"

    FaceApi:
      title: "FaceApi"
      type: object
      properties:
        url:
          type: string
          example: "https://faceapi.regulaforensics.com"
          description: "The URL of the Regula Face Web service to be used."
        mode:
          type: string
          example: "match"
          description: "The processing mode: \"match\" or \"match+search\"."
        search:
          type: object
          description: "A search filter that can be applied if the \"match+search\" mode is enabled. May include limit, threshold, group_ids. If the group_ids are specified, the search is performed only in these groups. Find more information in the <a href=\"https://dev.regulaforensics.com/FaceSDK-web-openapi/#tag/search/operation/search\" target=\"_blank\">OpenAPI documentation</a>."
          properties:
            limit:
              type: integer
              description: "The maximum number of results to be returned."
            threshold:
              type: number
              format: float
              description: "The similarity threshold."
            group_ids:
              type: array
              items:
                type: string
              description: " The groups where to conduct the search."
        threshold:
          type: integer
          example: 75
          description: "The similarity threshold, 0-100. Above 75 means that the faces' similarity is verified, below 75 is not."
        serviceTimeout:
          type: integer
          example: 3000
          description: "The Regula Face Web service requests timeout, ms."
        proxy:
          type: string
          example: "http://localhost:8080"
          description: "Proxy to use, should be set according to the <a href=\"https://curl.se/libcurl/c/CURLOPT_PROXY.html\" target=\"_blank\">cURL standard</a>."
        proxy_userpwd:
          type: string
          example: "user:pass"
          description: "Username and password to use for proxy authentication, should be set according to the <a href=\"https://curl.se/libcurl/c/CURLOPT_PROXYUSERPWD.html\" target=\"_blank\">cURL standard</a>."
        proxy_type:
          type: integer
          example: 0
          description: "Proxy protocol type, should be set according to the <a href=\"https://curl.se/libcurl/c/CURLOPT_PROXYTYPE.html\" target=\"_blank\">cURL standard</a>."
        childAgeThreshold:
          type: integer
          example: 13
          description: "The age threshold for the portrait comparison. Default: 13."
        childDocValidityYears:
          type: integer
          example: 5
          description: "Estimated duration of validity for a child's passport, years. Default: 5."
        livenessTransactionId:
          type: string
          description: "This parameter allows you to use a liveness transaction id instead of a selfie photo."

    VisualExtendedFieldItem:
      title: "VisualExtendedFieldItem"
      type: object
      required:
        - wFieldType
        - FieldName
        - StringsCount
        - StringsResult
        - Buf_Length
      properties:
        wFieldType:
          $ref: "./e-text-field-type.yml#/components/schemas/TextFieldType"
        FieldName:
          description: "Field symbolic name (null-terminated string)"
          type: string
        StringsCount:
          description: "Number of StringsResult array elements"
          type: number
        StringsResult:
          type: array
          description: "Array of recognizing probabilities for a each line of text field.
          Only for Result.VISUAL_TEXT and Result.MRZ_TEXT results."
          items:
            $ref: "#/components/schemas/StringRecognitionResult"
        Buf_Length:
          description: "Buf_Text text string length"
          type: number
        Buf_Text:
          type: string
          description: "Text field data in UTF8 format.
          Results of reading different lines of a multi-line field are separated by '^'"
        FieldMask:
          type: string
        Validity:
          type: integer
        InComparison:
          type: integer
        wLCID:
          $ref: "./e-lcid.yml#/components/schemas/LCID"
        Reserved2:
          type: integer
        Reserved3:
          type: integer

    StringRecognitionResult:
      title: "StringRecognitionResult"
      type: object
      description: "Describes single row recognition results in multi-line text field of a document"
      required:
        - SymbolsCount
        - StringResult
      properties:
        SymbolsCount:
          description: "Number of StringResult array elements"
          type: number
        StringResult:
          type: array
          description: "Array of recognition results for individual characters of a string"
          items:
            $ref: "#/components/schemas/SymbolRecognitionResult"
        Buf_Length:
          description: "Buf_Text text string length"
          type: number
        Buf_Text:
          type: string
          description: "Text field data in UTF8 format.
          Results of reading different lines of a multi-line field are separated by '^'"
        Reserved:
          type: integer

    SymbolRecognitionResult:
      title: "SymbolRecognitionResult"
      type: object
      description: "Describes a single character recognition results in the text field line"
      required:
        - CandidatesCount
        - ListOfCandidates
      properties:
        SymbolRect:
          allOf:
            - $ref: "#/components/schemas/RectangleCoordinates"
          description: "Coordinates of the symbol in the normalized image of the document"
        CandidatesCount:
          description: "Number of significant elements of ListOfCandidates array"
          type: number
        ListOfCandidates:
          type: array
          description: "Array of candidate characters. Sorted in descending order of recognition probabilities
          (the first element has highest probability)"
          items:
            $ref: "#/components/schemas/SymbolCandidate"
        BaseLineBottom:
          type: integer
        BaseLineTop:
          type: integer

    SymbolCandidate:
      title: "SymbolCandidate"
      required:
        - SymbolCode
        - SymbolProbability
      type: object
      description: "Describes an individual character recognition candidate"
      properties:
        SymbolCode:
          type: integer
          format: int64
          description: "Unicode symbol code"
        SymbolProbability:
          type: integer
          description: "character recognition probability (0–100,%)"
          minimum: 0
          maximum: 100
        Class:
          type: integer
        SubClass:
          type: integer

    RawImageContainerList:
      title: "RawImageContainerList"
      type: object
      required:
        - Count
        - Images
      properties:
        Count:
          type: integer
        Images:
          type: array
          items:
            $ref: "#/components/schemas/ImageData"

    DocumentPosition:
      title: "DocumentPosition"
      type: object
      required:
        - docFormat
        - Angle
        - Width
        - Height
        - Center
        - LeftBottom
        - LeftTop
        - RightBottom
        - RightTop
        - Dpi
      properties:
        docFormat:
          $ref: "./rt-doc-type-old.yml#/components/schemas/DocumentFormat"
        Angle:
          description: "Document rotation angle"
          type: number
        Width:
          description: "Document width"
          type: integer
        Height:
          description: "Document height"
          type: integer
        Center:
          $ref: "./common.yml#/components/schemas/Point"
        LeftBottom:
          $ref: "./common.yml#/components/schemas/Point"
        LeftTop:
          $ref: "./common.yml#/components/schemas/Point"
        RightBottom:
          $ref: "./common.yml#/components/schemas/Point"
        RightTop:
          $ref: "./common.yml#/components/schemas/Point"
        Dpi:
          type: integer
        Inverse:
          type: integer
        ObjArea:
          type: integer
        ObjIntAngleDev:
          type: integer
        PerspectiveTr:
          type: integer
        ResultStatus:
          type: integer

    GlaresCheckParams:
      title: "GlaresCheckParams"
      type: object
      properties:
        imgMarginPart:
          type: number
          format: float
          description: "Margin from the edges of the image. 0.35 = 35%"
          example: 0.35
        maxGlaringPart:
          type: number
          format: float
          description: "The maximum allowable part of the area occupied by the glare. The same: 0.06 = 6%"
          example: 0.0

    OcclusionCheckParams:
      title: "OcclusionCheckParams"
      type: object
      properties:
        maxOcclusionPart:
          type: number
          format: float
          description: "The maximum size for the occluded area of a document; only those exceeding this size will be validated"
          example: 0.01

    MDLDeviceEngagement:
      title: "MDLDeviceEngagement"
      type: integer
      description: "Enumeration contains possible data engagement methods with mDL"
      enum:
        - 0
        - 1
      x-enum-varnames:
        - "QR"
        - "NFC"
      x-enum-descriptions:
        - "Device Engagement using the QR code"
        - "Device Engagement using the NFC module"

    MDLDeviceRetrieval:
      title: "MDLDeviceRetrieval"
      type: integer
      description: "Enumeration contains possible data retrieval methods from mDL"
      enum:
        - 1
        - 2
        - 3
      x-enum-varnames:
        - "NFC"
        - "BLE"
        - "WIFI_AWARE"
      x-enum-descriptions:
        - "Device Retrieval using the NFC module"
        - "Device Retrieval using the Bluetooth module"
        - "Device Retrieval using the Wi-Fi Aware module"

    MDLServerRetrieval:
      title: "MDLServerRetrieval"
      type: integer
      enum:
        - 0
        - 1
      x-enum-varnames:
        - "WEB_API"
        - "OIDC"
      x-enum-descriptions:
        - "Retrieval using the Web API"
        - "Retrieval using OpenID Connect"