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".
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:
nc:DriverLicenseIdentification
element and child nc:IdentificationID
element)nc:PersonName
element and nc:PersonBirthDate
element)
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.)
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:
nc:Person
element containing the subset of child elements supported by the search, and a dls-ext:PersonPreviousRecord
element).nc:LocationAddress
element).nc:DriverLicense
element containing the subset of child elements supported by the search).A dls-ext:DriverLicenseHistoryMatch
contains the following additional information:
dls-ext:DriverConvictionHistory
element containing up to 50 j:DriverConviction
elements).dls-ext:DriverLicenseWithdrawalHistory
element containing up to 25 nc:DriverLicenseWithdrawal
elements).dls-ext:DUIAlcoholArrestHistory
element containing up to 15 dls-ext:DUIAlcoholArrest
elements).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
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:
...Match
child elements, but the sample XML instances show only a single match....History
element in a dls-ext:DriverLicenseHistoryMatch
can contain up to 15 child elements,
but the sample XML instances show only a single child element in each case.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.
This IEPD defines two namespaces, with the following prefixes:
dls-doc:DriverLicenseHistorySearchRequest
dls-doc:DriverLicenseHistorySearchResponse
dls-doc:DriverLicenseSearchRequest
dls-doc:DriverLicenseSearchResponse
For details, see the exchange schema, DriverLicenseSearchExchange.xsd.
dls-ext:DriverConvictionCitationArchiveID
(microfilm archive number: the term "Archive" was chosen to future-proof this XML markup, in case the archive moves to a digital format)dls-ext:DriverConvictionCitationTicketID
(citation ticket number)dls-ext:DriverLicenseHistoryMatch
dls-ext:DriverLicenseMatch
dls-ext:DriverLicenseCommercialClassColoradoCode
*dls-ext:DriverLicenseConvictionHistory
(container element for a set of j:DriverConviction
elements)dls-ext:DriverLicenseEndorsement
(container element for a pair of nc:DriverLicenseEndorsementCode
and nc:DriverLicenseEndorsementText
elements)dls-ext:DriverLicenseWithdrawalHistory
(container element for a set of dls-ext:DriverLicenseWithdrawal
elements)dls-ext:DriverLicenseWithdrawal
(augmented nc:DriverLicenseWithdrawal
element)dls-ext:DrivingRestrictionColoradoCode
*dls-ext:DUIAlcoholArrestHistory
(container element for a set of dls-ext:DUIAlcoholArrest
elements)dls-ext:DUIAlcoholArrest
dls-ext:PersonPreviousRecord
* 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.
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.
xsi:schemaLocation
and xmlns:xsi
attributes before sending the SOAP messagesThe 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.
The initial implementation of this IEPD uses CICS programs that map each information exchange to a COMMAREA.
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
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
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.
The following mapping notes apply to the initial implementation of this IEPD.
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.
The test cases are presented as SOAP messages. See the documentation/test_cases directory.
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:
|
|
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 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:
|
|
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).