{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/azure-ai-foundry/json-schema/azure-ai-foundry-face-detection-result-schema.json",
  "title": "FaceDetectionResult",
  "description": "Response for detect API.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_superseded/azure-ai-foundry-detect-api-openapi.yml#/components/schemas/FaceDetectionResult",
  "type": "object",
  "properties": {
    "faceId": {
      "$ref": "#/$defs/Azure.Core.uuid",
      "description": "Unique faceId of the detected face, created by detection API and it will expire 24 hours after the detection call. To return this, it requires 'returnFaceId' parameter to be true."
    },
    "recognitionModel": {
      "$ref": "#/$defs/RecognitionModel",
      "description": "The 'recognitionModel' associated with this faceId. This is only returned when 'returnRecognitionModel' is explicitly set as true."
    },
    "faceRectangle": {
      "$ref": "#/$defs/FaceRectangle",
      "description": "A rectangle area for the face location on image."
    },
    "faceLandmarks": {
      "$ref": "#/$defs/FaceLandmarks",
      "description": "An array of 27-point face landmarks pointing to the important positions of face components. To return this, it requires 'returnFaceLandmarks' parameter to be true."
    },
    "faceAttributes": {
      "$ref": "#/$defs/FaceAttributes",
      "description": "Face attributes for detected face."
    }
  },
  "required": [
    "faceRectangle"
  ],
  "$defs": {
    "AccessoryItem": {
      "type": "object",
      "description": "Accessory item and corresponding confidence level.",
      "properties": {
        "type": {
          "$ref": "#/$defs/AccessoryType",
          "description": "Type of the accessory."
        },
        "confidence": {
          "type": "number",
          "format": "float",
          "description": "Confidence level of the accessory type. Range between [0,1].",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "type",
        "confidence"
      ]
    },
    "AccessoryType": {
      "type": "string",
      "description": "Type of the accessory.",
      "enum": [
        "headwear",
        "glasses",
        "mask"
      ],
      "x-ms-enum": {
        "name": "AccessoryType",
        "modelAsString": true,
        "values": [
          {
            "name": "headwear",
            "value": "headwear",
            "description": "Head wear."
          },
          {
            "name": "glasses",
            "value": "glasses",
            "description": "Glasses."
          },
          {
            "name": "mask",
            "value": "mask",
            "description": "Mask."
          }
        ]
      }
    },
    "Azure.Core.uuid": {
      "type": "string",
      "format": "uuid",
      "description": "Universally Unique Identifier"
    },
    "BlurLevel": {
      "type": "string",
      "description": "Indicates level of blurriness.",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "x-ms-enum": {
        "name": "BlurLevel",
        "modelAsString": true,
        "values": [
          {
            "name": "low",
            "value": "low",
            "description": "Low blur level."
          },
          {
            "name": "medium",
            "value": "medium",
            "description": "Medium blur level."
          },
          {
            "name": "high",
            "value": "high",
            "description": "High blur level."
          }
        ]
      }
    },
    "BlurProperties": {
      "type": "object",
      "description": "Properties describing any presence of blur within the image.",
      "properties": {
        "blurLevel": {
          "$ref": "#/$defs/BlurLevel",
          "description": "An enum value indicating level of blurriness."
        },
        "value": {
          "type": "number",
          "format": "float",
          "description": "A number indicating level of blurriness ranging from 0 to 1.",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "blurLevel",
        "value"
      ]
    },
    "ExposureLevel": {
      "type": "string",
      "description": "Indicates level of exposure.",
      "enum": [
        "underExposure",
        "goodExposure",
        "overExposure"
      ],
      "x-ms-enum": {
        "name": "ExposureLevel",
        "modelAsString": true,
        "values": [
          {
            "name": "underExposure",
            "value": "underExposure",
            "description": "Low exposure level."
          },
          {
            "name": "goodExposure",
            "value": "goodExposure",
            "description": "Good exposure level."
          },
          {
            "name": "overExposure",
            "value": "overExposure",
            "description": "High exposure level."
          }
        ]
      }
    },
    "ExposureProperties": {
      "type": "object",
      "description": "Properties describing exposure level of the image.",
      "properties": {
        "exposureLevel": {
          "$ref": "#/$defs/ExposureLevel",
          "description": "An enum value indicating level of exposure."
        },
        "value": {
          "type": "number",
          "format": "float",
          "description": "A number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure.",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "exposureLevel",
        "value"
      ]
    },
    "FaceAttributes": {
      "type": "object",
      "description": "Face attributes for the detected face.",
      "properties": {
        "age": {
          "type": "number",
          "format": "float",
          "description": "Age in years."
        },
        "smile": {
          "type": "number",
          "format": "float",
          "description": "Smile intensity, a number between [0,1].",
          "minimum": 0,
          "maximum": 1
        },
        "facialHair": {
          "$ref": "#/$defs/FacialHair",
          "description": "Properties describing facial hair attributes."
        },
        "glasses": {
          "$ref": "#/$defs/GlassesType",
          "description": "Glasses type if any of the face."
        },
        "headPose": {
          "$ref": "#/$defs/HeadPose",
          "description": "3-D roll/yaw/pitch angles for face direction."
        },
        "hair": {
          "$ref": "#/$defs/HairProperties",
          "description": "Properties describing hair attributes."
        },
        "occlusion": {
          "$ref": "#/$defs/OcclusionProperties",
          "description": "Properties describing occlusions on a given face."
        },
        "accessories": {
          "type": "array",
          "description": "Properties describing any accessories on a given face.",
          "items": {
            "$ref": "#/$defs/AccessoryItem"
          }
        },
        "blur": {
          "$ref": "#/$defs/BlurProperties",
          "description": "Properties describing any presence of blur within the image."
        },
        "exposure": {
          "$ref": "#/$defs/ExposureProperties",
          "description": "Properties describing exposure level of the image."
        },
        "noise": {
          "$ref": "#/$defs/NoiseProperties",
          "description": "Properties describing noise level of the image."
        },
        "mask": {
          "$ref": "#/$defs/MaskProperties",
          "description": "Properties describing the presence of a mask on a given face."
        },
        "qualityForRecognition": {
          "$ref": "#/$defs/QualityForRecognition",
          "description": "Properties describing the overall image quality regarding whether the image being used in the detection is of sufficient quality to attempt face recognition on."
        }
      }
    },
    "FaceLandmarks": {
      "type": "object",
      "description": "A collection of 27-point face landmarks pointing to the important positions of face components.",
      "properties": {
        "pupilLeft": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eye pupil."
        },
        "pupilRight": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eye pupil."
        },
        "noseTip": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose tip."
        },
        "mouthLeft": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the mouth left."
        },
        "mouthRight": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the mouth right."
        },
        "eyebrowLeftOuter": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eyebrow outer."
        },
        "eyebrowLeftInner": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eyebrow inner."
        },
        "eyeLeftOuter": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eye outer."
        },
        "eyeLeftTop": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eye top."
        },
        "eyeLeftBottom": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eye bottom."
        },
        "eyeLeftInner": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the left eye inner."
        },
        "eyebrowRightInner": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eyebrow inner."
        },
        "eyebrowRightOuter": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eyebrow outer."
        },
        "eyeRightInner": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eye inner."
        },
        "eyeRightTop": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eye top."
        },
        "eyeRightBottom": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eye bottom."
        },
        "eyeRightOuter": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the right eye outer."
        },
        "noseRootLeft": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose root left."
        },
        "noseRootRight": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose root right."
        },
        "noseLeftAlarTop": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose left alar top."
        },
        "noseRightAlarTop": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose right alar top."
        },
        "noseLeftAlarOutTip": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose left alar out tip."
        },
        "noseRightAlarOutTip": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the nose right alar out tip."
        },
        "upperLipTop": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the upper lip top."
        },
        "upperLipBottom": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the upper lip bottom."
        },
        "underLipTop": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the under lip top."
        },
        "underLipBottom": {
          "$ref": "#/$defs/LandmarkCoordinate",
          "description": "The coordinates of the under lip bottom."
        }
      },
      "required": [
        "pupilLeft",
        "pupilRight",
        "noseTip",
        "mouthLeft",
        "mouthRight",
        "eyebrowLeftOuter",
        "eyebrowLeftInner",
        "eyeLeftOuter",
        "eyeLeftTop",
        "eyeLeftBottom",
        "eyeLeftInner",
        "eyebrowRightInner",
        "eyebrowRightOuter",
        "eyeRightInner",
        "eyeRightTop",
        "eyeRightBottom",
        "eyeRightOuter",
        "noseRootLeft",
        "noseRootRight",
        "noseLeftAlarTop",
        "noseRightAlarTop",
        "noseLeftAlarOutTip",
        "noseRightAlarOutTip",
        "upperLipTop",
        "upperLipBottom",
        "underLipTop",
        "underLipBottom"
      ]
    },
    "FaceRectangle": {
      "type": "object",
      "description": "A rectangle within which a face can be found.",
      "properties": {
        "top": {
          "type": "integer",
          "format": "int32",
          "description": "The distance from the top edge if the image to the top edge of the rectangle, in pixels."
        },
        "left": {
          "type": "integer",
          "format": "int32",
          "description": "The distance from the left edge if the image to the left edge of the rectangle, in pixels."
        },
        "width": {
          "type": "integer",
          "format": "int32",
          "description": "The width of the rectangle, in pixels."
        },
        "height": {
          "type": "integer",
          "format": "int32",
          "description": "The height of the rectangle, in pixels."
        }
      },
      "required": [
        "top",
        "left",
        "width",
        "height"
      ]
    },
    "FacialHair": {
      "type": "object",
      "description": "Properties describing facial hair attributes.",
      "properties": {
        "moustache": {
          "type": "number",
          "format": "float",
          "description": "A number ranging from 0 to 1 indicating a level of confidence associated with a property.",
          "minimum": 0,
          "maximum": 1
        },
        "beard": {
          "type": "number",
          "format": "float",
          "description": "A number ranging from 0 to 1 indicating a level of confidence associated with a property.",
          "minimum": 0,
          "maximum": 1
        },
        "sideburns": {
          "type": "number",
          "format": "float",
          "description": "A number ranging from 0 to 1 indicating a level of confidence associated with a property.",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "moustache",
        "beard",
        "sideburns"
      ]
    },
    "GlassesType": {
      "type": "string",
      "description": "Glasses type of the face.",
      "enum": [
        "noGlasses",
        "readingGlasses",
        "sunglasses",
        "swimmingGoggles"
      ],
      "x-ms-enum": {
        "name": "GlassesType",
        "modelAsString": true,
        "values": [
          {
            "name": "noGlasses",
            "value": "noGlasses",
            "description": "No glasses on the face."
          },
          {
            "name": "readingGlasses",
            "value": "readingGlasses",
            "description": "Normal glasses on the face."
          },
          {
            "name": "sunglasses",
            "value": "sunglasses",
            "description": "Sunglasses on the face."
          },
          {
            "name": "swimmingGoggles",
            "value": "swimmingGoggles",
            "description": "Swimming goggles on the face."
          }
        ]
      }
    },
    "HairColor": {
      "type": "object",
      "description": "An array of candidate colors and confidence level in the presence of each.",
      "properties": {
        "color": {
          "$ref": "#/$defs/HairColorType",
          "description": "Name of the hair color."
        },
        "confidence": {
          "type": "number",
          "format": "float",
          "description": "Confidence level of the color. Range between [0,1].",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "color",
        "confidence"
      ]
    },
    "HairColorType": {
      "type": "string",
      "description": "Name of the hair color.",
      "enum": [
        "unknown",
        "white",
        "gray",
        "blond",
        "brown",
        "red",
        "black",
        "other"
      ],
      "x-ms-enum": {
        "name": "HairColorType",
        "modelAsString": true,
        "values": [
          {
            "name": "unknownHairColor",
            "value": "unknown",
            "description": "Unknown."
          },
          {
            "name": "white",
            "value": "white",
            "description": "White."
          },
          {
            "name": "gray",
            "value": "gray",
            "description": "Gray."
          },
          {
            "name": "blond",
            "value": "blond",
            "description": "Blond."
          },
          {
            "name": "brown",
            "value": "brown",
            "description": "Brown."
          },
          {
            "name": "red",
            "value": "red",
            "description": "Red."
          },
          {
            "name": "black",
            "value": "black",
            "description": "Black."
          },
          {
            "name": "other",
            "value": "other",
            "description": "Other."
          }
        ]
      }
    },
    "HairProperties": {
      "type": "object",
      "description": "Properties describing hair attributes.",
      "properties": {
        "bald": {
          "type": "number",
          "format": "float",
          "description": "A number describing confidence level of whether the person is bald.",
          "minimum": 0,
          "maximum": 1
        },
        "invisible": {
          "type": "boolean",
          "description": "A boolean value describing whether the hair is visible in the image."
        },
        "hairColor": {
          "type": "array",
          "description": "An array of candidate colors and confidence level in the presence of each.",
          "items": {
            "$ref": "#/$defs/HairColor"
          }
        }
      },
      "required": [
        "bald",
        "invisible",
        "hairColor"
      ]
    },
    "HeadPose": {
      "type": "object",
      "description": "3-D roll/yaw/pitch angles for face direction.",
      "properties": {
        "pitch": {
          "type": "number",
          "format": "float",
          "description": "Value of angles."
        },
        "roll": {
          "type": "number",
          "format": "float",
          "description": "Value of angles."
        },
        "yaw": {
          "type": "number",
          "format": "float",
          "description": "Value of angles."
        }
      },
      "required": [
        "pitch",
        "roll",
        "yaw"
      ]
    },
    "LandmarkCoordinate": {
      "type": "object",
      "description": "Landmark coordinates within an image.",
      "properties": {
        "x": {
          "type": "number",
          "format": "float",
          "description": "The horizontal component, in pixels."
        },
        "y": {
          "type": "number",
          "format": "float",
          "description": "The vertical component, in pixels."
        }
      },
      "required": [
        "x",
        "y"
      ]
    },
    "MaskProperties": {
      "type": "object",
      "description": "Properties describing the presence of a mask on a given face.",
      "properties": {
        "noseAndMouthCovered": {
          "type": "boolean",
          "description": "A boolean value indicating whether nose and mouth are covered."
        },
        "type": {
          "$ref": "#/$defs/MaskType",
          "description": "Type of the mask."
        }
      },
      "required": [
        "noseAndMouthCovered",
        "type"
      ]
    },
    "MaskType": {
      "type": "string",
      "description": "Type of the mask.",
      "enum": [
        "faceMask",
        "noMask",
        "otherMaskOrOcclusion",
        "uncertain"
      ],
      "x-ms-enum": {
        "name": "MaskType",
        "modelAsString": true,
        "values": [
          {
            "name": "faceMask",
            "value": "faceMask",
            "description": "Face mask."
          },
          {
            "name": "noMask",
            "value": "noMask",
            "description": "No mask."
          },
          {
            "name": "otherMaskOrOcclusion",
            "value": "otherMaskOrOcclusion",
            "description": "Other types of mask or occlusion."
          },
          {
            "name": "uncertain",
            "value": "uncertain",
            "description": "Uncertain."
          }
        ]
      }
    },
    "NoiseLevel": {
      "type": "string",
      "description": "Indicates level of noise.",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "x-ms-enum": {
        "name": "NoiseLevel",
        "modelAsString": true,
        "values": [
          {
            "name": "low",
            "value": "low",
            "description": "Low noise level."
          },
          {
            "name": "medium",
            "value": "medium",
            "description": "Medium noise level."
          },
          {
            "name": "high",
            "value": "high",
            "description": "High noise level."
          }
        ]
      }
    },
    "NoiseProperties": {
      "type": "object",
      "description": "Properties describing noise level of the image.",
      "properties": {
        "noiseLevel": {
          "$ref": "#/$defs/NoiseLevel",
          "description": "An enum value indicating level of noise."
        },
        "value": {
          "type": "number",
          "format": "float",
          "description": "A number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level.",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "noiseLevel",
        "value"
      ]
    },
    "OcclusionProperties": {
      "type": "object",
      "description": "Properties describing occlusions on a given face.",
      "properties": {
        "foreheadOccluded": {
          "type": "boolean",
          "description": "A boolean value indicating whether forehead is occluded."
        },
        "eyeOccluded": {
          "type": "boolean",
          "description": "A boolean value indicating whether eyes are occluded."
        },
        "mouthOccluded": {
          "type": "boolean",
          "description": "A boolean value indicating whether the mouth is occluded."
        }
      },
      "required": [
        "foreheadOccluded",
        "eyeOccluded",
        "mouthOccluded"
      ]
    },
    "QualityForRecognition": {
      "type": "string",
      "description": "Indicates quality of image for recognition.",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "x-ms-enum": {
        "name": "QualityForRecognition",
        "modelAsString": true,
        "values": [
          {
            "name": "low",
            "value": "low",
            "description": "Low quality."
          },
          {
            "name": "medium",
            "value": "medium",
            "description": "Medium quality."
          },
          {
            "name": "high",
            "value": "high",
            "description": "High quality."
          }
        ]
      }
    },
    "RecognitionModel": {
      "type": "string",
      "description": "The recognition model for the face.",
      "enum": [
        "recognition_01",
        "recognition_02",
        "recognition_03",
        "recognition_04"
      ],
      "x-ms-enum": {
        "name": "RecognitionModel",
        "modelAsString": true,
        "values": [
          {
            "name": "recognition_01",
            "value": "recognition_01",
            "description": "The default recognition model for \"Detect\". All those faceIds created before 2019 March are bonded with this recognition model."
          },
          {
            "name": "recognition_02",
            "value": "recognition_02",
            "description": "Recognition model released in 2019 March."
          },
          {
            "name": "recognition_03",
            "value": "recognition_03",
            "description": "Recognition model released in 2020 May."
          },
          {
            "name": "recognition_04",
            "value": "recognition_04",
            "description": "Recognition model released in 2021 February. It's recommended to use this recognition model for better recognition accuracy."
          }
        ]
      }
    }
  }
}