README for Warrant Message Exchange Schemas WHAT THIS IS This is a set of UML datamodels, schemas, and example XML instance documents for the exchange of messages. It utilizes the Global Justice XML Datamodel (GJXDM) version 3.0.3. THE WARRANT PROCESS A Warrant is issued by a Court. This Warrant can be an initial issuance, or it can be a cancellation, withdrawal, or modification of a previously issued Warrant. STEP 1: "Issue" message is sent to Law Enforcement agency. The Law Enforcement agency is tasked with serving warrants. STEP 2: Law Enforcement agency sends a "Response" to Court. This does NOT indicate any action has been taken or service performed. It is only an acknowledgement, including confirmation of some of the basic information about the service subject, as received. STEP 3: Law Enforcement agency serves the warrant. STEP 4: Law Enforcement agency sends a "Service" message to the Court, asserting that the warrant has been served, and describing some details of the service event. STEP 4a: Law Enforcement agency also sends a copy of the Service Message to DOJ for recordkeeping purposes. THE THREE WARRANT MESSAGES, IN MORE DETAIL: WARRANT ISSUED MESSAGE This message will be sent from a circuit court to law enforcement when a circuit court official has signed a warrant document authorizing the arrest of a defendant/subject. The data elements contained in this message consists of court information regarding the issuance of a warrant (date, type of warrant, court official who signed the warrant, etc.) and personal information regarding a defendant/subject (name, alias, personal descriptors, etc.) WARRANT RESPONSE MESSAGE This message will be sent by law enforcement. It is automatically sent to the issuing circuit court acknowledging receipt of the electronic court information received by law enforcement. The data elements contained in this message consists of a date and time the electronic record was received by law enforcement and the relevant court information needed to identify the court case. WARRANT SERVICE MESSAGE This message will be sent by law enforcement to a circuit court when a subject/defendant has been personally served with a warrant document. The data elements contained in this message consists of the date and time of service and the relevant court information needed to identify a case. WHAT IS ALL THIS STUFF? Constructing schemas for message exchange is a somewhat surprisingly complex task; and the cost associated with change of message formats, when a mission-critical system has been put into service, can be high. Therefore, the best practices, as evolving in the GJXDM/NIEM community, emphasize a very deliberate and well-documented procedure of analysis, design, and compilation of resources. The most detailed and heavyweight standard for developing message content is the "Information Exchange Package Documentation", or "IEPD", specification. The GJXDM IEPD spec is available at: http://it.ojp.gov/topic.jsp?topic_id=196 The NIEM IEPD specification is, at time of writing, still evolving. Current work can be found at: http://niem.gtri.gatech.edu/repository/specs.iepd This Warrant specification complies with the GJXDM IEPD specification. I ASK AGAIN: WHAT IS ALL THIS STUFF? OK ok. Getting to that. This IEPD implements the Warrant Exchanges in the context of a "Reference" schema that defines the universal model that all of these warrant exchanges adhere to. This "Reference" schema is constrained for each exchange type in the appropriate Exchange subfolder so that XML Schema Validation may be applied to instances. Folder Hierarchy and description WarrantSchemas | +-v1.0 | +-codes-schema.xsd | : Base codes schema. This is invariant and will only | have one file | +-README.TXT | : This file | +-requested.xml | : Wantlist for the SSGT | +-Subset.zip | : File generated by the SSGT | +-Warrant GJXDM CODES.doc | +-Warrant GJXDMMappingDataElements.xls | : Spreadsheet documenting all Warrant exchanges, | extensions and cardinality +-Warrant GJXDMMappingDataElements.xml | : The same as above, but in XML Spreadsheet format | +-jxdm | : Folder containing a complete GJXDM subset for all | exchanges generated from Subset.zip, above | +-Models | : Folder containing the model diagrams | +-Unconstrained Reference Schemas | : Folder containing an unconstrained extension "reference" | schema that supports all Warrant Exchanges. | Not actually used. | +-WarrantIssue | | : Folder supporting the WarrantIssue Exchange | | | +-WarrantIssue.xsd | | : Warrant Issue exchange schema. It contains exactly | | *one* XML Element declaration. | | That "Document" element is the root element of | | the message payload. | | When validating message content, THIS IS THE | | NECESSARY SCHEMA TO PROVIDE TO YOUR PARSER. | | This schema imports its core GJXDM content | | (namespace "http://www.it.ojp.gov/jxdm/3.0.3") | | by import from extension-schema.xsd. | | | +-extension-schema.xsd | | : Project-specific (and Wisconsin-specific) extensions | | to the GJXDM. This gets its core GJXDM content | | (namespace "http://www.it.ojp.gov/jxdm/3.0.3") | | by import from constraint-schema.xsd. | | | +-constraint-schema.xsd | | : additional restrictions (cardinality and simple | | datatype) applied to the GJXDM. | | This gets its core GJXDM content | | (namespace "http://www.it.ojp.gov/jxdm/3.0.3") | | INDIRECTLY from the subset schema, | | jxdm/3.0.3/jxdm.xsd. constraint-schema begins life | | as a *copy* of the content in jxdm.xsd, and is | | edited to provide further constraints. | | | +-requested.xml | | : Wantlist for GJXDM supporting only this exchange | | | +-Subset.zip | | : SSGT output of requested.xml | | | +-jxdm | | : Constrained GJXDM Subset with some cardinality | | specifications for this exchange (superseded | | by the more complete set of cardinalities | | specified in constraint-schema.xsd). | | | +-Unconstrained jxdm | : Unconstrained GJXDM subset. Not actually used | +-WarrantResponse | : Folder containing the same stuff as WarrantIssue | +-WarrantService | : Folder containing the same stuff as WarrantIssue | +-XMLInstances : Folder containing exchange instance examples You can skip the rest of this, mostly. All of the other Schema content (and there is a *lot* of it) is sucked into the parser through the magic of XML Schema Import mechanism. The imports are chained; the parser just keeps following, until it has read all of them into an in-memory representation. In general, that's not your problem, EXCEPT that the GJXDM is so big that it has been known to blue-screen people's workstations by consuming too much memory. Be aware of that. Treat it as any other resource-intensive compute process. One thing that really does help you in this respect: the folder called "Subset". This folder you really *can* ignore, unless you're curious. But it's absolutely necessary, and it's of great benefit. Subset of what? Subset of the whole big 32-ton datamodel that is happily known as GJXDM. This subset has been constructed to provide only those type definitions and item declarations that your parser will actually need in order to validate the messages defined in these schemas. This cuts *way* down on that out-of-memory problem during validation. The rest of this complicated and elaborate structure is designed, not so much for your benefit, but for the benefit of anyone who is designing, editing, analyzing, updating, or extending the schemas. The main thing to remember is: DON'T EDIT ANYTHING. Poke around all you like, but don't make changes, or you may have unexpected results. So, on to the rest. The "XMLInstance" folder contains examples of what the messages look like. *Very* helpful in a lot of contexts. In particular, it shows how the namespace and schemaLocation attributes are used. (Obviously, your exact value for the schemaLocation will change; or you can just leave it out altogether, if everyone involved in Warrant message exchange is confident that they're all using local copies that are identical.) The .png files with names similar to the message type folder names are UML diagrams of the datamodel of each corresponding message type. Also very helpful if you want to understand the structure of the messages. (Note that "Issue" is big, and the others are pretty little.) During analysis, the mappings between legacy CCAP item names, and the new, GJXDM-based names identified in these schemas, were recorded. These mappings are collected in the "GJXDM Mapping Document.xls" spreadsheet. "codes-schema.xsd" is the equivalent of a lookup table, for those code enumerations that needed to be created specifically for Warrant Messaging. Note that this file is bundled in the root of the archive! For many validation or code-generation tools, it may be necessary to make a local copy of this file in the *message-type* folder ("WarrantIssue", "WarrantResponse", "WarrantService") and adjust the schemaLocation value (in the import directives in extension-schema.xsd) accordingly. ABOUT CODE-GENERATION FRAMEWORKS Enterprise software development frameworks are increasingly featuring code-generation utilities that work from XML data interface definitions. Ordinarily, they create empty "stub" classes, exposing methods whose parameters are value classes mimicking the XML datatypes. It's then up to you to put working code inside the stubs, but undeniably a lot of the heavy lifting has been done for you. Unfortunately, code generation, as of this writing, tends to be uneven. Many frameworks don't support all of the features of XML Schema. YMMV. If you are using Java, you are in luck. The JAXB (Java API for XML Binding) library includes a utility, called "XJC", that can create Java classes from schemas. We know it works with these Message schemas, because we use JAXB code generation to make sure we didn't screw up a namespace URL or something in the schemas themselves. If you are using .NET, the picture is less clear. Microsoft's XML-Binding code generation focuses on generating from Web Service WSDLs, rather than from Schemas. As of this writing, the so-called "schema-first" code generation is still somewhat buggy. However, Microsoft has been very forthcoming about fixing reported bugs, so it may be smooth sailing by the time you're reading this. We have no information about other platforms/frameworks at this point.