NIEM IEPD: Driver License Search

This IEPD describes the format of four information exchanges. These information exchanges form two pairs:

Note: For consistency with NIEM terminology, this IEPD uses the term "driver license" (that is, without a trailing apostrophe and letter "s") instead of "driver's license".

Request format

The contents of a Driver License Search request and a Driver License History request are identical. The only difference in their formats is the root element: dls-doc:DriverLicenseSearchRequest or dls-doc:DriverLicenseHistorySearchRequest. The word "History" indicates that you want license details with history.

A request can contain either or both of the following search criteria:

Sample Driver License History Search request: DriverLicenseHistorySearchRequest.xml

(A request supports only a subset of the child elements of nc:PersonName, as shown in the supplied sample.)

Response format

A Driver License Search response can contain details of up to five driver licenses that match the request search criteria. The response presents each match in a dls-ext:DriverLicenseMatch element. Similarly, a Driver License History Search response can contain up to five dls-ext:DriverLicenseHistoryMatch elements.

A dls-ext:DriverLicenseHistoryMatch element contains a superset of the elements in a dls-ext:DriverLicenseMatch element.

Both responses contain the following details:

A dls-ext:DriverLicenseHistoryMatch contains the following additional information:

For the initial implementation of this IEPD for the State of Colorado, both responses begin with hardcoded caveats (in nc:CaveatText elements), indicating that only the Colorado database was searched.

Sample Driver License History Search response: DriverLicenseHistorySearchResponse.xml

Repeatable structures in the response format

Typically, where the response can contain a structure that repeats, the sample XML instances contain only a single example of that structure, for conciseness. For example:

There is one exception. A driver license (nc:DriverLicense element) can specify multiple endorsements and restrictions. The sample instances show two examples of each to illustrate the difference between their repeating structure markup. The code element and the text element for each restriction are enclosed in an nc:DriverLicenseRestriction element; however, NIEM defines no such equivalent parent element for endorsement code and text, so this IEPD introduces the dls-ext:DriverLicenseEndorsement element.

Extended components

This IEPD defines two namespaces, with the following prefixes:

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

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

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

* All of the elements whose names end with ColoradoCode are based on a text type; their contents are not restricted to enumerated code values. For details on the contents of these elements, contact the State of Colorado. (The developers of this IEPD understand the consequences of this for NIEM conformance.)

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

All other elements in these information exchanges belong to either the NIEM Core (nc: prefix) namespace or the Justice (j: 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.

These SOAP messages include a sample SOAP fault response: the format of this response is identical for a Driver License Search and a Driver License History Search.

This IEPD also contains two sample web service description (WSDL) files: one for a Driver License Search, the other for a Driver License History Search.

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 each information exchange to a COMMAREA.

COMMAREA for Driver License Search

The layout of this COMMAREA is defined by a COBOL copybook that consists of the top-level declaration:

01  DDQ-COMMAREA

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

Request COBOL copybook: DDQ-INPUT-MESSAGE.txt

Response COBOL copybook: DDQ-OUTPUT-MESSAGE.txt

COMMAREA for Driver License History Search

The layout of this COMMAREA is defined by a COBOL copybook that consists of the top-level declaration:

01  DDH-COMMAREA

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

Request COBOL copybook: DDH-INPUT-MESSAGE.txt

Response COBOL copybook: DDH-OUTPUT-MESSAGE.txt

Mapping illustrations

For an illustration of how the sample XML instances map to the 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 can either provide the LICENSE-NUM or INPUT-PICCODE as valid input.
  2. No validation of the input fields will be done. If INPUT-PICCODE is used a SOAP fault will occur if the DDH-LAST-NAME is not supplied or blank.
  3. The response can be either no data indicating no match, one record indicating the customer was found, or up to five records only in the case where the INPUT-PICCODE was used as input and twins were found.
  4. If an error occurs the DDQ-ERROR-MESSAGE (for Driver License Search) or the DDH-ERROR-MESSAGE (for Driver License History Search) will be set to the error message to return. Otherwise, it will be blank.
  5. Driver License History Search only:
    1. Everything up to DDH-CITATION-LINE is the same data as was returned by PCPDDQ (Driver License Search).
    2. Up to 50 citations, 25 departmental actions, and 15 DUIs will be returned.

About the "Maps" comments in the sample XML instances

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

<nc:PersonGivenName>Harry<!-- Maps: NAME-FIRST --></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. Strictly speaking, such implementation-specific details probably do not belong in an IEPD, but 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 test cases are presented as SOAP messages. See the documentation/test_cases directory.

Test cases for Driver License Search

Test case ID Exchange type Exchange contents
001a Driver License Search request PIN: 021290001
Response Simple record: regular adult license (one on file), status valid, regular address, no endorsements or restrictions
001b Driver License Search request PICCODE: SLUMBA050169
Response Same as 001a
002a Driver License Search request PIN: 081120001
Response Confidential address record: valid duplicate adult license (multiple regulars on file), confidential address, 1 endorsement, 1 restriction
002b Driver License Search request PICCODE: CONFIA121278
Response Same as 002a
003a Driver License Search request PIN: 922157580
Response Restraint record: regular adult license (multiple docs on file including a valid ID), status is REVOKE PER SE .08 MULTIPLE, no endorsements or restrictions
003b Driver License Search request PICCODE: SLUMBB072767
Response Same as 003a
004a Driver License Search request PIN: 090920001
Response CDL record: CDL adult license (one on file), valid, class A, regular address, multiple restrictions, multiple endorsements
004b Driver License Search request PICCODE: CBITET010960
Response Same as 004a
005a Driver License Search request PIN: 061670004
Response Skeleton record: returns only name, sex code, DOB, and May Apply status
005b Driver License Search request PICCODE: SLUMBJ120239
Response Same as 005a
006a Driver License Search request PIN: 943330118
Response Two valid documents: regular adult license, regular address, 1 endorsement
006b Driver License Search request PICCODE: TEST D012068 (note the space in the PICCODE)
Response Same as 006a
007a Driver License Search request PIN: 922347256
Response CDL restraint/regular valid: regular adult license (many docs), valid, CDL restraint on file, regular address
007b Driver License Search request PICCODE: cdlnor040852
Response Same as 007a
008 Driver License Search request PICCODE: BELL M060954
Response 5 twin records:
BELL,MICHAEL
Returns only name, regular address, sex code, DOB, and May Apply status
BELL,MALLORY
Returns only name, regular address, sex code, DOB, and May Apply status
BELL,MOE
Returns only name, regular address, sex code, DOB, and May Apply status
BELL,MINDI,CHRISTIN
Returns name, regular address, sex code, DOB, and May Apply status, has no Valid Reg license (other multiple docs on file)
BELL,MICHAEL,G
Returns Name, regular address, sex code, DOB, and May Apply Status, has EXP Reg license (other multiple docs on file), M endorsement
009a Driver License Search request PIN: 943330101
Response No record found (NRF)
009b Driver License Search request PICCODE: thronp010101
Response Same as 009a: no record found (NRF)
010 Driver License Search request No PIN or PICCODE
Response SOAP fault

Test cases for Driver License History Search

Test case ID Exchange type Exchange contents
001a Driver License History Search request PIN: 021290001
Response Simple citation record
001b Driver License History Search request PICCODE: SLUMBA050169
Response Same as 001a
002a Driver License History Search request PIN: 061310383
Response Simple DUI record
002b Driver License History Search request PICCODE: ROGERSB010168
Response Same as 002a
003a Driver License History Search request PIN: 992730060
Response Simple active departmental action
003b Driver License History Search request PICCODE: SLUMBI010245
Response Same as 003a
004a Driver License History Search request PIN: 922157580
Response Active departmental actions, EC, and citations - multiples
004b Driver License History Search request PICCODE: SLUMBB072767
Response Same as 004a
005a Driver License History Search request PIN: 030730001
Response Current valid with previous reinstatements
005b Driver License History Search request PICCODE: MARRIC031763
Response Same as 005a
006 Driver License History Search request PICCODE: TEST N010151
Response 5 twin records:
  • TEST,NIA
  • TEST,NAME
  • TEST,NETEL,BIB
  • TEST,NOW,CBI
  • TEST,NET,RENEW
007a Driver License History Search request PIN: 943330101
Response No record found (NRF)
007b Driver License History Search request PICCODE: thronp010101
Response Same as 007a: no record found (NRF)
008 Driver License History Search request PIN: 9200112
Response SOAP fault

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).