BWS Messages Schema Documentation

The schema-namespace for the XML-messages returned by the BWS operations Enroll, Verify, Identify and QualityCheck currently is
http://schemas.bioid.com/2012/02/BWSMessages (XSD file).

Such an XML-message contains information about the performed operation itself, such as a unique ID, a flag indicating whether the operation succeeded and a list of operation specific errors. It also contains information about each sample that has been received by the operation, including sample specific errors that might have occurred. The XML-structure of the message, starting with the root element OperationResults is as follows:

  • JobID contains a so called GUID that uniquely identifies the operation to which this message belongs. Using this ID, the operation can later be identified, for example in the monthly settlement.
  • Command names the executed operation.
  • Succeeded simply repeats the return-value of the operation.
  • Face is a boolean value that is only set by the enrollment operation indicating whether a template for the trait face is available or not.
  • Periocular is a boolean value that is only set by the enrollment operation indicating whether a template for the trait periocular is available or not.
  • Voice is a boolean value that is only set by the enrollment operation indicating whether a template for the trait voice is available or not.
  • Samples lists all samples received by the operation:
    • Sample describes a single sample in the samples collection by providing a
      • Trait attribute, specifying the trait the sample belongs to, and a
      • Suitalble attribute, a flag indicating whether this sample was suitable for the operation. If set to false, a list of errors follows:
      • Errors lists sample specific errors if Suitable is set to false or warnings in case Suitable is set to true:
        • Error describes a single error by providing a
          • Code, a string identifying the error, the error-
          • Message itself, and some optional
          • Details, which might describe the error message a bit more.
      • Tags is an optional element and may contain tags associated with the sample like:
        • RightEye providing in its attributes X and Y the cartesian coordinates of the right iris center (or eye center if iris was not found).
        • LeftEye providing in its attributes X and Y the cartesian coordinates of the left iris center (or eye center if iris was not found).
        • HeadMovementDirection reports the degree of head rotation between the previous image sample and this image sample. It is calculated by the photo fake defender (as used with the Verify, Identify and Enroll API calls when the LiveFaceDetection flag is set). Valid values are between 0 and 359 degrees.
  • Errors lists non sample specific errors as reported by the operation:
    • Error describes a single error by providing a
      • Code, a string identifying the error, the error-
      • Message itself, and some optional
      • Details, which might describe the error message a bit more.
  • Statistics contains some statistical informations about the performed operation:
    • ProcessingTime shows the amount of time that was needed to perform the operation.
    • TotalServiceTime shows the total amount of time the server needed to service the operation.

The parsing of such an XML-message string is very simple. Here is an example of how to do it in C#:


// lets parse the message string 'messages' as it might have been returned
// by a call to Enroll, Verify, Identify or QualityCheck:
using (XmlReader reader = XmlReader.Create(new StringReader(messages)))
{
    XmlSerializer serializer = new XmlSerializer(typeof(JobResult), "http://schemas.bioid.com/2012/02/BWSMessages");
    JobResult result = (JobResult)serializer.Deserialize(reader);
}
// these are the classes we use for the deserialization:
[XmlRoot(ElementName = "OperationResults", Namespace = "http://schemas.bioid.com/2012/02/BWSMessages")]
public class JobResult
{
    public Guid JobID { get; set; }
    public string Command { get; set; }
    public bool Succeeded { get; set; }
    public bool? Face { get; set; }
    public bool? Periocular { get; set; }
    public bool? Voice { get; set; }
    public List<JobSample> Samples { get; set; }
    public List<JobMessage> Errors { get; set; }
}
[XmlType(TypeName = "Sample")]
public class JobSample
{
    [XmlAttribute]
    public Trait Trait { get; set; }
    [XmlAttribute]
    public bool Suitable { get; set; }
    public List<JobMessage> Errors { get; set; }
    // in case you are interested in these tags
    public SampleTags Tags { get; set; }
}
[XmlType(TypeName = "Error")]
public class JobMessage
{
    public string Code { get; set; }
    public string Message { get; set; }
    public string Details { get; set; }
}
[XmlType(TypeName = "Tags")]
public class SampleTags
{
    public Cartesian RightEye { get; set; }
    public Cartesian LeftEye { get; set; }
    public int? HeadMovementDirection { get; set; }
}
public struct Cartesian
{
    [XmlAttribute]
    public double X { get; set; }
    [XmlAttribute]
    public double Y { get; set; }
}