regulaforensics/documentreader-web-openapi

OpenAPI definitions of Regula Document Reader web application

Regula Document Reader OpenAPI definitions

Main GitHub repository

• https://github.com/regulaforensics/DocumentReader-web-openapi

Clients

• JavaScript client for the browser and node.js based on axios
• Java client compatible with jvm and android
• Python 3.5+ client
• C# client for .NET & .NET Core

Structure

• index.yml - definition entry point
• common.yml - small enums and popular models
• rt.yml - definitions import of all possible results types
• e - *.yml - files with huge enum definitions
• rt - *.yml - files describing results types
• p - *.yml - files describing endpoints

Updating clients according to the current spec

To update clients, use update clients GitHub action. Specify title PR and press run. For each client PR with changes will be created.

⚠️ NOTE: Static typed clients, such as Java or C#, require adding all new enums to update-models.sh ENUM_MAPPINGS section.

⚠️ NOTE: For some clients generator produces not-valid client code. See update-models.sh for ad-hocks fixing generator issues.

⚠️ NOTE: Do not edit generated code. Create wrappers, decorators, etc in ext folder.

💡 All clients have RawResultItem container that is used for deserialization for undescribed types. This container is a simple map/dict.

Spec validation

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli validate --recommend -i /local/index.yml 

Building Redoc single page html documentation

Edit rt.yml - remove components.schemas.ResultItem.discriminator node

Edit rt-authenticity.yml - remove components.schemas.AuthenticityCheckResultItem.discriminator

Then run next command:

npx redoc-cli bundle "$PWD/index.yml" --output document-reader-static-doc.html \
--options.maxDisplayedEnumValues=5 --options.theme.logo.gutter="20px" \
--options.theme.colors.primary.main="#8a53cb" --options.expandResponses="all" \
--options.expandSingleSchemaField --options.hideDownloadButton --options.jsonSampleExpandLevel="6"

Bundle scheme to single .json file

npx openapi-generator-cli generate -i index.yml  -g openapi  --skip-validate-spec

documentreader-web-openapi's Issues

Describe 403 and 400 responses

New client checklist

[github-action] release clients from openapi repo action

add processParam.updateOCRValidityByGlare into request

boolean, when enabled OCR field validity will be updated with | tr_GlaresOnField value, if there is a glare over the text field on the image. Disabled by default.

Rename model TFDSIDList -> FDSIDList

text field value original validity move to source validity

text field source validity = source validity & value original validity

From conversation:

Hleb Albau, [23.07.20 18:12]
еще я забыл что такое  originalValidity

Andrey Ilyin, [23.07.20 18:13]
оно из самого модуля. например, что контрольная сумма не та или несуществующий код страны.

Hleb Albau, [23.07.20 18:13]
а это не дублирует инфу из validityList

Andrey Ilyin, [23.07.20 18:14]
нет, там из лексического анализа.

Hleb Albau, [23.07.20 18:16]
как тут не запутаться)

Hleb Albau, [23.07.20 18:25]
т.е. если у нас будет не та контрольная сумма для баркода, но то значение, которое попало в лекс само по себе валидное, то будет следующее
- originalValidity - error
-validirtList - ok
?

Andrey Ilyin, [23.07.20 18:25]
ну это же просто 8)

My points:

1. (optional) Remove original validity from text field value
2. set error for text field source validity, when original is broken
3. (optional) Add source validity error message(maybe not localized string, like barcode.checksum.error)

Add processParam.checkRequiredTextFields into request

boolean, when enabled each field in template will be checked for value presence and if the field is marked as required, but has no value, it will have "error" in validity status. Disabled by default.

add getter methods to obtain field value by its name

publish "FieldName" in Text result for text fields

when there are many fields with ft_Other type that differ only by FieldName, we need to provide convenient way to find and retrieve field value by its name/caption

Rename FDSIDList.ICAO to FDSIDList.ICAOCode

FDSIDList field doesn't contain property ICAO, it should be ICAOCode. Also minLength and maxlength should be 3 instead of 4.

Current situation:

ICAO:
  type: string
  minLength: 4
  maxLength: 4
  description: "ICAO code of the issuing country"

E.g. FDSIDList object returned from server:

{
  "Count": 2,
  "ICAOCode": "HRV",
  "List": [
    14800,
    12510
  ],
  "dCountryName": "Croatia",
  "dFormat": 2,
  "dMRZ": true,
  "dType": 11,
  "dYear": "2009"
}

hint message for 400 response

Right now lib do not return validation error hint on bad input.
For easier debugging, may be we should add some message from core?

add processParam.fastDocDetect to request

Boolean, when enabled shorten the list of candidates to process during document detection in a single image process mode. Reduces processing time for specific backgrounds. Enabled by default.

add processParam.generateDoublePageSpreadImage into request

boolean, when enabled together with "doublePageSpread" and there is a passport with two pages spread in the image, pages will be cropped, straightened and aligned together, as if the document was captured on a flatbed scanner.

add new TextFieldType members

    ft_Date_of_Insurance_Expiry = 596,
    ft_Mortgage_by = 597,
    ft_Old_Document_Number = 598,
    ft_Old_Date_of_Issue = 599,
    ft_Old_Place_of_Issue = 600,
    ft_DLClassCode_LR_From = 601,
    ft_DLClassCode_LR_To = 602,
    ft_DLClassCode_LR_Notes = 603,
    ft_DLClassCode_MR_From = 604,
    ft_DLClassCode_MR_To = 605,
    ft_DLClassCode_MR_Notes = 606,
    ft_DLClassCode_HR_From = 607,
    ft_DLClassCode_HR_To = 608,
    ft_DLClassCode_HR_Notes = 609,
    ft_DLClassCode_HC_From = 610,
    ft_DLClassCode_HC_To = 611,
    ft_DLClassCode_HC_Notes = 612,
    ft_DLClassCode_MC_From = 613,
    ft_DLClassCode_MC_To = 614,
    ft_DLClassCode_MC_Notes = 615,
    ft_DLClassCode_RE_From = 616,
    ft_DLClassCode_RE_To = 617,
    ft_DLClassCode_RE_Notes = 618,
    ft_DLClassCode_R_From = 619,
    ft_DLClassCode_R_To = 620,
    ft_DLClassCode_R_Notes = 621,
    ft_DLClassCode_CA_From = 622,
    ft_DLClassCode_CA_To = 623,
    ft_DLClassCode_CA_Notes = 624,

Prepare repository for open to public

Replace "^" with "\n" in all clients in values

здесь нужно сделать с графикой RFID как с текстами RFID - там указывается вместо fieldrect OriginDG и Tag

здесь нужно сделать с графикой RFID как с текстами RFID - там указывается вместо fieldrect OriginDG и Tag

Originally posted by @ikliashchou in https://github.com/regulaforensics/api/pull/111/files

add processParam.imageQA.angleThreshold and processParam.imageQA.dpiThreshold into request

processParam.imageQA.dpiThreshold
number

this parameter sets threshold for Image QA check of the presented document physical dpi. If actual document dpi is below this threshold, check will fail. If not set, defaults to 150.

processParam.imageQA.angleThreshold
number

this parameter sets threshold for Image QA check of the presented document perspective angle in degrees. If actual document perspective angle is above this threshold, check will fail. If not set, defaults to 5.

403, 400 JSON error reports

It's required to implement JSON responses for 400 and 403 error codes instead of HTML.
It may look like:

{

"type": "error",

"code": "string",

"details": "string",

"location": "string",

"moreInfo": {}

}

add /api/ping endpoint description

Add ProcessParams.forceDocID

ProcessParams:
type: object
properties:
forceDocID:
type: number
description: "Force use of specific template ID and skip document type identification step."

Describe Authenticity(20) result type

process input params

"processParam":{

"scenario":"FullProcess"
"doublePageSpread":true
"fieldTypesFilter":[8, 5] // surname & DOB
"multipageProcessing":true
"log":true
"dateFormat":"MM/dd/yyyy"
"documentIdList":[2146864762]
"resultTypeOutput":[1,15]
"disableFocusingCheck":true
"alreadyCropped":true
"imageDpiOutMax":200
}

еще могут быть

"customParams":{"ocrFree":{"mask":"DDDD DDDD DDDD","lcid":0}}}})"

"faceMetadata":[{"ID":0,"bounds":{"height":327,"width":327,"x":123,"y":218},"rollAngle":89}

"imageInputParam":{"frameBottom":1072,"frameLeft":113,"frameRight":1806,"frameTop":7,"height":1080.0,"type":254,"width":1920.0}

"recpassParam":{"docIdFilter":"-318410998"},

[ci] auto pull request with updated models in clients on manual action

• js
• java
• python
• csharp

Add New Images Result Type - 37

TextFieldType add fullname alias

Schema validation as PR check

add processParam.matchTextFieldMask into request

Boolean, when disabled, text field OCR will be done as is and then the recognized value will be matched to the field mask for validity. If enabled, we are trying to read a field value with maximum efforts to match the mask and provide a correctly formatted value, making assumptions based on the provided field mask in the template. Enabled by default.

offline signle-page html documenation using redoc

Current redoc limitations:

• there is not enum description support. See Redocly/redoc#234
• before generation, .rt.yml file should be changed manually

New result type RPRM_ResultType_Status = 37

{
      "result_type": 37,
      "light": 0,
      "buf_length": 8,
      "list_idx": 0,
      "page_idx": 0,
  "Status": {
    "statusComplete": 0,
    "statusOptical": 0,
    "detailsOptical": {
      "statusMRZ": 0,
      "statusText": 0,
      "statusDocType": 1,
      "statusSecurity": 1,
      "statusImageQA": 2,
      "pagesCount": 2
    },
    "statusRFID": 0,
    "detailsRFID": {
      "statusPA": 0,
      "statusAA": 1,
      "statusCA": 0,
      "statusTA": 1,
      "statusBAC": 2,
      "statusPACE": 2
    },
    "statusPortrait": 2,
    "statusStopList": 2
  }
}

add "log" to processParam

{ "processParam": { "log":true } }

if "log": true then in response there will be "log" field with base64 string of transaction processing log

we have to implement changes in request/response and mirror them in all clients

• JS

• Python

• Java

• C#

describe RPRM_ResultType_Authenticity result

RPRM_ResultType_Authenticity = TAuthenticityCheckList

update all clients