ValidationsObject

Validations is an object that contains the results of the validations for an attempt. It is returned in response to Validation, Applicants and other requests under the validations key.

Validations contains several blocks of checks.

Liveness

An object contains a filled verdict field which is formed from the verdicts of all sub-blocks by conjunction. The verdict field may be null if no Liveness checks have been performed.

The sub-block data is stored under the details key in the list.

Each sub-block stores the following fields:

• verdict - verification result
• score - verification score
• name - verification name
• additionalInfo - additional info about check

note

If sub-block check is disabled, it will be absent from the details list.
If the check should have been executed but was not, the verdict field of sub-block will be null.

The following sub-blocks are possible:

• FaceLiveness - face Liveness check.
• DeepFake - Check for signs of DeepFake technology usage. (Experimental feature)

When FaceLiveness check fails, the most likely attack type will be written in the additionalInfo field in the following format:

"additionalInfo": {
  "attackType": "3d_mask",
  "attackTypeConfidence": 0.99899864
}

where attackType is the attack type, and attackTypeConfidence is the confidence score.

Attack types:

1. Replay attacks: The camera is shown a facial image or video being played back on the screen of another device (smartphone, tablet, monitor).

2. Attacks using flat images Photo: The camera is presented with a regular printed face photo, not cut out along the contour. Cutout image (regions): The camera is shown a photo cut out along the contour of the head or face (possibly with a small gap) to simulate the volume of a living person. 2D mask (2d_mask): The camera is presented with an image cut out along the head contour, physically "worn" on the attacker's face (for example, glued or held by hands) to add realism through movement and perspective.

3. Attacks using three-dimensional objects 3D mask (3d_mask): The camera is shown a three-dimensional mask reproducing facial features. This can be: Realistic silicone or latex mask worn on the face. Paper or cardboard mask assembled from polygons to create volume.

Quality

An object contains a filled verdict field which is formed from the verdicts of all sub-blocks by conjunction. The verdict field may be null if no quality checks have been performed.

The sub-block data is stored under the details key in list.

Each sub-block stores the following fields:

• verdict — verification result
• score — verification score
• name — verification name

note

If sub-block check is disabled, it will be absent from the details list. And if the check should have been executed but was not, the verdict field of sub-block will be null.

The following sub-blocks are possible:

• FaceQuality - face quality check.

When FaceQuality check fails, the failed checks and their numerical values will be listed in the additionalInfo field in the following format:

"additionalInfo": {
  "failReasons": [
    {
        "check": "sharpness",
        "result": "0.120000"
    },
    {
        "check": "gray_scale",
        "result": "0"
    },
    {
        "check": "eye_distance",
        "result": "12.621400"
    }
  ]
}

where failReasons is a list enumerating all triggered checks. Each element in the list is an object where check is the check name and result is the numerical value of the check.

List of possible checks:

• noise: The image is too noisy.
• dynamic_range: The image has too high dynamic range.
• sharpness: The image is too sharp.
• pitch: The face in the image has a large pitch angle.
• yaw: The face in the image has a large yaw angle.
• face_overflow: The face extends beyond the image border.
• face_overflow_score_v: Amount of vertical overflow beyond the border.
• face_overflow_score_h: Amount of horizontal overflow beyond the border.
• eye_distance: The face in the image is too small.
• glasses: Sunglasses detected on the face.
• face_size_on_image: Face size relative to the image is too small.
• gray_scale: The image is in grayscale.

Matching

An object contains a filled verdict field which is formed from the verdicts of all sub-blocks by conjunction. The verdict field may be null if no matching checks have been performed.

The sub-block data is stored under the details key in list. Each sub-block stores following fields:

• verdict — verification result.
• score — verification score.
• name — verification name.

note

If sub-block check is disabled, it will be absent from the details list.
If the check should have been executed but was not, the verdict field of sub-block will be null.

The following sub-blocks are possible:

• FaceMatching - face matching check.

MotionControl

Checking the results of video motion control.

An object contains a verdict field that can include the following data:

• true — all actions were performed correctly.
• false — one of the actions was performed incorrectly.
• null — attempt does not contain motion control data.

The motionControlInfo field contains data on motion control results.

The data is a list where each element of the list is an object with the following fields:

• pattern — the name of the pattern to be performed (up, right, left, closer, farther).
• result — whether the pattern was performed by the user or not.

Example of ValidationsObject

{
  "liveness": {
    "verdict": true,
    "details": [
      {
        "name": "FaceLiveness",
        "verdict": true,
        "score": 0.99,
        "additionalInfo": {
          "attackType": "3d_mask",
          "attackTypeConfidence": 0.99899864
        }
      },
      {
        "name": "LivenessReflection",
        "verdict": true,
        "score": 0.8,
        "additionalInfo": null
      },
      {
        "name": "DeepFake",
        "verdict": false,
        "score": 0.001,
        "additionalInfo": null
      }
    ]
  },
  "quality": {
    "verdict": true,
    "details": [
      {
        "name": "FaceQuality",
        "verdict": false,
        "score": null,
        "additionalInfo": {
          "failReasons": [
            {
                "check": "sharpness",
                "result": "0.120000"
            },
            {
                "check": "gray_scale",
                "result": "0"
            },
            {
                "check": "eye_distance",
                "result": "12.621400"
            }
          ]
        }
      }
    ]
  },
  "matching": {
    "verdict": true,
    "details": [
      {
        "name": "FaceMatching",
        "verdict": true,
        "score": 0.0,
        "additionalInfo": null
      }
    ]
  },
  "motionControl": {
    "verdict": false,
    "motionControlInfo": [
      {
          "pattern": "up",
          "result": true
      },
      {
          "pattern": "left",
          "result": false
      }
    ]
  }
}