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
This IEPD defines two namespaces, with the following prefixes:
dns-doc:DriverNameSearchRequest
dns-doc:DriverNameSearchResponse
For details, see the exchange schema, DriverNameSearchExchange.xsd.
dns-ext:PersonMatch
dns-ext:PersonPreviousRecord
For details, see the extension schema, DriverNameSearchExtension.xsd.
All other elements in these information exchanges belong to the NIEM Core (nc:
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.
This IEPD also contains a sample web service description (WSDL) file.
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 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.
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: 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.
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).