README for Protection Order 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 PROTECTION ORDER PROCESS A Protection Order (which can be a Temporary Restraining Order, Injunction, or other order) is issued by a Court. The issuance can be: - an Initial Issuance, - a Modification of an existing order, or - a Dismissal of a case. Upon the issuance of a Protection Order by a circuit court official, requiring personal service on a party, the appropriate documents are submitted to a law enforcement agency. A law enforcement agency will prepare their file for service on a Designated Subject (Respondent) as outlined in the Protection Order documents and will also initiate a case with the Department of Justice. THE PROTECTION ORDER INTERFACE The Protection Order Interface is a specification for exchange of electronic data between Justice Partners in the Protection Order Process. The specification includes a definition of sequence of information exchanged, according to the actions performed by the various participants. The interplay of actions and messages can be stated as a series of discrete steps: STEP 1: "Issue" message is sent to Law Enforcement agency. The Law Enforcement agency is tasked with serving the Protection Order document. STEP 2: Law Enforcement agency sends a "Response" to Court. The Response Message does not indicate that any action has been taken. It is only an acknowledgement of receipt of the Issue message, including confirmation of some of the basic information about the service subject. STEP 2a: Law Enforcement Agency also forwards a copy of the Issue message to DOJ for recordkeeping purposes. STEP 3: Law Enforcement agency serves the Protection Order document. STEP 4: Law Enforcement agency sends a "Service" message to the Court, asserting that a Protection Order has been served, along with details of the service event, such as date & time served, officer serving document, etc. STEP 4a: Law Enforcement agency also sends a copy of the Service Message to DOJ for recordkeeping purposes. THE THREE PROTECTION ORDER MESSAGES, IN MORE DETAIL: PROTECTION ORDER ISSUED MESSAGE This message will be sent from a circuit court to law enforcement when a petition for a Temporary Restraining Order or an Injunction has been issued by a circuit court official. The data elements contained in this message consist of court information regarding a TRO or Injunction (date, name of the parties involved in a petition or injunction, relief requested, expiration date of the TRO or Injunction, etc.), limited personal information regarding a Restricted Person (Petitioner) and personal information regarding a Designated Subject (Respondent) (name, address, personal descriptors, etc.) PROTECTION ORDER RESPONSE MESSAGE This message will be sent by law enforcement to a circuit court. This message is an automated receipt of acknowledgment when an Issue message has been received by a law enforcement agency from a circuit court. The data elements contained in this message consist of a date and time the electronic record was received by law enforcement, and the relevant court information needed to identify a case. PROTECTION ORDER SERVICE MESSAGE This message will be sent by law enforcement to a circuit court when a designated subject (Respondent) has been personally served or substitute service has been obtained, regarding a TRO or Injunction document. The data elements contained in this message consist of the date and time of service and the relevant service information (person served, law enforcement officer, etc.) 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 ponderous 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 Protection Order specification is not an IEPD, but it's a fairly close precursor. Hopefully, these message specifications will be reissued in the form of a full NIEM IEPD after the NIEM 1.1 specification is published. If and when that happens, messages valid according to this published specification will still be valid under the full-boat IEPD (UNLESS errors have been found in this specification, and the IEPD publication event is seen as a good time to correct such errors. Obviously, forward-compatibility of a bug cannot be guaranteed.) I ASK AGAIN: WHAT IS ALL THIS STUFF? OK ok. Getting to that. This IEPD implements the Protection Order Exchanges in the context of a "Reference" schema that defines the universal model that all of these Protection Order 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 ProtectionOrderSchemas | +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 | + Protection Order GJXDM CODES.doc | + Protection Order GJXDMMappingDataElements.xls | : Spreadsheet documenting all Protection Order | exchanges, extensions and cardinality | + Protection Order 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 | Protection Order Exchanges. Not actually used. | + Protection Order Issue | | : Folder supporting the ProtectionOrderIssue | | Exchange | | | + ProtectionOrderIssue.xsd | | : Protection Order 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 | + ProtectionOrderResponse | : Folder containing the same stuff as ProtectionOrderIssue | + ProtectionOrderService | : Folder containing the same stuff as ProtectionOrderIssue | +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 Protection Order 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 Protection Order 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 ("ProtectionOrderIssue", " ProtectionOrderResponse", " ProtectionOrderService") 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.