NIEM IEPD: Driver Name Search

This IEPD describes the format of two information exchanges: a request to search for a driver by name, and the corresponding response.

A Driver Name Search request contains a single nc:PersonName element. The request supports only a subset of the child elements of nc:PersonName, as shown in the supplied sample request.

Sample request: DriverNameSearchRequest.xml

A Driver Name Search response can contain up to 50 dns-ext:PersonMatch elements. Each of these elements contains the details of a driver whose name matches the request. These details include the driver's name, date of birth, address, and license identification.

Sample response: DriverNameSearchResponse.xml

Extended components

This IEPD defines two namespaces, with the following prefixes:

dns-doc
Consists of the request and response document root (or "exchange") elements:

For details, see the exchange schema, DriverNameSearchExchange.xsd.

dns-ext
Consists of the extension types introduced by this IEPD (including the types for the exchange elements, described above) and the following extension elements:

For details, see the extension schema, DriverNameSearchExtension.xsd.

All other elements in these information exchanges belong to the NIEM Core (nc: prefix) namespace.

Sample SOAP messages for a web service

The initial (and perhaps only) implementation of these information exchanges is a web service (SOAP 1.1 over HTTP).

For NIEM conformance, this IEPD describes the information exchanges independently of a web service implementation: that is, without a SOAP envelope. This IEPD contains these "SOAP-free" sample XML instances and their related schemas in the recommended directory path, exchange_files.

For clarity and completeness, this IEPD also presents SOAP messages, in the documentation/soap/sample directory. The bodies of these SOAP messages are identical to the corresponding SOAP-free request and response instances, except that they do not contain comments that map the XML elements to their underlying programmatic field names.

This IEPD also contains a sample web service description (WSDL) file.

Remove xsi:schemaLocation and xmlns:xsi attributes before sending the SOAP messages

The sample SOAP messages contain xsi:schemaLocation and corresponding xmlns:xsi attributes:

<soapenv:Envelope

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation=" pairs of namespace URIs and schema file locations "

>

These files specify the xsi:schemaLocation attribute so that, if you open the files in an XML editor, the editor can use the attribute value to locate the schema files stored in this IEPD, and validate the file.

These attributes are not intended for use in a SOAP message that you send to another computer. The attributes specify a relative path to the schema files that are correct only in the context of the directory structure and file names in this IEPD.

When creating your own SOAP messages to send to another computer, omit the xsi:schemaLocation attributes and corresponding xmlns:xsi attributes.

Mapping

The initial implementation of this IEPD uses CICS programs that map the information exchanges to a COMMAREA. The layout of this COMMAREA is defined by a COBOL copybook that consists of the top-level declaration:

01  DDA-COMMAREA

followed by declarations for the "input" (request) and "output" (response) messages:

Request COBOL copybook: DDA-INPUT-MESSAGE.txt

Response COBOL copybook: DDA-OUTPUT-MESSAGE.txt

For an illustration of how request and response XML instances map to these implementation-specific COBOL copybooks, see the PDF files in the documentation/mapping directory.

Red highlighting in the map does not necessarily indicate an error: it indicates only that a field in the copybook does not map to that specific XML instance. For example, the error message field maps to a SOAP fault.

Implementation-specific mapping notes

The following mapping notes apply to the initial implementation of this IEPD:

  1. A user may provide any portion of the DDA-NAME in the input message. However, some portion of the DDA-LAST-NAME is required.
  2. For any fields not provided, such as DDA-MIDDLE-NAME, blanks are substituted, giving the effect of a wild card.
  3. The input fields are not validated. If the DDA-LAST-NAME is not supplied or is blank, the web service returns a SOAP fault message.
  4. The input represents a starting point for the search; the output returns up to 50 results. If they match the other portions on the DDA-NAME supplied.
  5. Less than 50 results will be returned when the name is close to the end of the file.
  6. SUFFIX is only used as a secondary search field. If the initial result set for FIRST, MIDDLE, and LAST name does not have any records with suffixes, but a SUFFIX match was provided, then no results will be returned.
  7. The search is done by DDA-NAME as well as DDA-AKA-NAME. The output might return a record whose current name (DDA-NAME) is different than the search criteria. For example, searching for a surname starting with "PAB" might return a record with a current surname of "REED", because that record's DDA-AKA-NAME has a surname of "PABALAN" (due to a name change).

About the "Maps" comments in the sample XML instances

The SOAP-free XML instances contain comments such as this:

<nc:PersonGivenName>Harry<!-- Maps: DDA-FIRST-NAME --></nc:PersonGivenName>

The sample SOAP fault message also contains one of these comments.

These comments refer to programmatic field names in the initial implementation of this IEPD. These inline comments are helpful to the developers who need to map the fields in their programs to the appropriate XML elements.

Test cases

The documentation/test_cases directory contains test cases presented as SOAP messages:

Test case ID Exchange type Exchange contents
001 Request Given name and surname
Response Single record returned
002 Request Partial given name (first few letters) and surname
Response Multiple records returned, illustrating "twins": the partial name supplied and the birth date are the same for two different people (this might or might not represent twins in the sense of two people born to the same mother on the same day)
003 Request Partial surname
Response Multiple records returned, with and without "confidential" address (the response supplies a fake address that matches the driver license)
004 Request Partial surname
Response Multiple records returned, with a name change (the web service searches both NAME and AKA-NAME, so the response can include records that have a different current surname than the partial name searched for)
005 Request Partial surname (first letter only)
Response Multiple records returned: maximim number of records (50) returned
006 Request Surname and (deliberately non-existent) given name
Response No records returned
007 Request Given name only (no surname)
Response No records returned: SOAP fault message returned instead (a request must specify at least the first letter of a surname)

The test cases are actual examples of transmitted SOAP messages; they deliberately omit the xsi:schemaLocation attributes that an XML editor could use to locate the XML schemas on a particular file system, and then validate the messages.

Instead, this IEPD includes an XML schema that you can use with a command-line validation tool such as xmllint (included in the libxml2 toolkit).