GJXDM Information Exchange Package Documentation Methodology, Naming and Design Rules (MNDR)
Section II – Information Exchange Package Documentation Overview
Working Draft 04, 28October 2005 (FTF Meeting)
Document identifier:
wd-ijtc-mndr-sec2
Location:
Editor:
[List your editors here; check whether “Editor” header should be plural]
Tom Carlson, NationalCenter for State
Contributors:
[List your contributors here]
[Optionally list them in the Acknowledgments appendix instead]
Abstract:
[Supply your own summary of the technical purpose of the document.] This document provides an overview of Information Exchange Package Descriptions.
Status:
[Describe the status and stability of the specification and where to send comments.] This document is updated periodically on no particular schedule. Send comments to the editor.
[This is boilerplate; to use, fix the hyperlinks:] Committee members should send comments on this specification to the list. Others should subscribe to and send comments to the list. To subscribe, send an email message to with the word "subscribe" as the body of the message.
[This is boilerplate; to use, fix the hyperlinks:] For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the XXX TC web page (
[If a Committee Specification or OASIS Standard:] The errata page for this specification is at
Table of Contents
Introduction
1.1 Definitions
1.1.1 Global Justice Information Sharing Initiative (Global)
1.1.2 Global Justice XML Data Model (GJXDM)
1.1.3 GJXDM Information Exchange Package (GIEP)
1.1.4 GJXDM Information Exchange Package Description (GIEPD)
1.1.5 Schemas
1.1.6 Instance Documents
1.1.7 Additional Definitions
2Types and Uses
2.1 Samples / Project starting points
2.2 Jurisdictional Standards
2.3 Geopolitical Standards
2.4 Exchange Documents, Reference Documents
3Mandatory and Optional Components of a GJXDM Information Exchange Package Description (GIEPD)
3.1 Process Documentation
3.2 Support Documentation
3.2.1 Sample Documents
3.2.2 Other Supporting Documentation
3.3 Schemas
3.3.1 Subset Schema
3.3.2 Document Schema
3.3.3 Extension Schema
3.3.4 Constraint Schema
3.4 References
4References
4.1 Normative
Appendix A. Acknowledgments
Appendix B. Revision History
Appendix C. Notices
Introduction
[Provide an introductory chapter, indicating if any parts of it are non-normative.]
1.1Definitions
[The following is boilerplate. Most specifications will need this and the corresponding bibliography entry.] The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [???][???][RFC2119].
Include a usage note describing the expected level of knowledge required by this document, along with pointers to additional references (so it’s clear that this document assumes prior knowledge of “basic” XML concepts such as cardinality
1.1.1Global Justice Information Sharing Initiative (Global)
The efforts of the Global Justice Information Sharing Initiative (Global) Advisory Committee (GAC) have direct impact on the work of more than 1.2 million justice professionals. The importance of the organization's mission, however, positions Global to impact citizens of the U.S., Canada, and beyond. Global's mission — the efficient sharing of data among justice entities — is at the very heart of modern public safety and law enforcement.
Global is a “group of groups,” representing more than thirty independent organizations spanning the spectrum of law enforcement, judicial, correctional, and related bodies. Member organizations participate in Global out of shared responsibility and shared belief that, together, they can bring about positive change in interorganizational communication and data sharing..
(Cite
1.1.2Global Justice XML Data Model (GJXDM)
The Global JXDM is an XML standard designed specifically for criminal justice information exchanges, providing law enforcement, public safety agencies, prosecutors, public defenders, and the judicial branch with a tool to effectively share data and information in a timely manner. The Global JXDM removes the burden from agencies to independently create exchange standards, and because of its extensibility, there is more flexibility to deal with unique agency requirements and changes. Through the use of a common vocabulary that is understood system to system, Global JXDM enables access from multiple sources and reuse in multiple applications.
(Cite
1.1.3GJXDM Information Exchange Package (GIEP)
An “Information Exchange Package” represents a set of data that is transmitted for a specific business purpose. It is the actual XML instance that delivers the payload or information. (The word “package” as used herein refers to a package of the actual data, not a package of artifacts documenting the structure and content of the data.) An Information Exchange Package can be prefixed with “GJXDM” to indicate or highlight that the IEP is GJXDM-conformant, as in “GJXDM Information Exchange Package.” The fact that an IEP is GJXDM-conformant may be readily apparent from the context, so it is not absolutely necessary to use the word “GJXDM” even if the IEP is GJXDM-conformant.
(Cite GJXDM Information Exchange Package DocumentationGuidelines, Hulme.)
1.1.4GJXDM Information Exchange Package Documentation (GIEPD)
“Information Exchange Package Documentation” is a collection of artifacts that describe the structure and content of an Information Exchange Package. It does not specify other interface layers (such as web services). It can optionally be prefixed with “GJXDM” to indicate or highlight that a resulting IEP is GJXDM-conformant. This term replaces “Exchange Document.”
(Cite GJXDM Information Exchange Package DocumentationGuidelines, Hulme.)
1.1.5Schemas
XML Schemas are the mechanism used to define GIEPs within the exchange defined by the GIEPD. There are four different Schemas involved in a GIEPD.
1.1.5.1Subset Schema
Because of the size and complexity of the full GJXDM schema, it is generally a good practice to create a “subset schema” that removes unused GJXDM components.
(Cite GJXDM Information Exchange Package Documentation Guidelines, Hulme.)
The Subset Schema is a version of the entire data model with portions removed. Because all elements in the data model are optional, the full data model may be substituted for a Subset Schema. Any instance document that validates against the Subset Schema MUST also validate against the model as a whole. The Subset Schema is imported into the exchange via the Document Schema.
The Subset Schema is redefinition of the GJXDM namespace with unused elements and type definitions removed. It takes the place of the whole data model. The Subset Schema narrows the focus on what information is actually being exchanged while also reducing the processing load required by validation.
( Include the XML schema spec definitions; (element/type definitions are called components, etc) in order to be as precise as possible.
In other words, first normalize terms/definitions to the XSD specs, then double check that we haven’t used the same word in both generic and specific contexts.
1.1.5.2Document Schema
The Document Schema defines the contents and content structure of the instance and specifies which parts of the GJXDM (and extensions) are expected. The Document Schema must be included since there would be no IEP Documentation without it.
(Cite GJXDM Information Exchange Package Documentation Guidelines, Hulme.)
Basically, the Document Schema provides the wrapper around an exchange. It defines the root element and imports the other schemas required by the exchange, including the Subset Schema or the model as a whole.
1.1.5.3Extension Schema
The Extension Schema defines local extensions.
(Cite GJXDM Information Exchange Package Documentation Guidelines, Hulme.)
While large, the data model can not include every element and type that could possibly be used in the context of an exchange of justice information. Some types of information are specific to particular jurisdictions or areas. It would be inappropriate and impractical for these local types of information to be contained in a national-scope data model.
The Extension Schema provides a means for this type of local information to included in exchanges within the local area. Extension Schemas are imported into the exchange via the Document Schema.
1.1.5.4Constraint Schema
The Constraint Schema embeds local constraints into GJXDM definitions.
(Cite GJXDM Information Exchange Package Documentation Guidelines, Hulme.)
Constraint Schemas provide a variety of functionality. They provide a recommended place for enforcing cardinality rules. They also provide a means to enforce business rules that cannot be represented within the limitations of a Subset Schema.
When used solely to enforce cardinality, Constraint Schemas take the place of the Subset Schema for validation purposes. Enforcing cardinality is the more common use of a Constraint Schema.
When used to enforce business rules that go beyond the capacity of a Subset Schema, then Instance Documents are validated against both the Subset Schema (or data model as a whole) and the Constraint Schema in parallel. The Constraint Schema temporarily “stands-in” for the Subset Schema.Validation against such a Constraint Schema will only validate the additional business rules, not GJXDM conformance itself. For an Instance Document to be valid, it MUST validate against both the Subset Schema (or data model as a whole) and the Constraint Schema.
In addition, alternate constraint methods MAY be used, where the schema itself is more general and value constraints are applied using different XML methodologies (such as Schematron)]
1.1.6Instance Documents
[Sample instances] should include samples of both simple and complex information exchanges. Realistic data should be used (although data should be “sanitized” to omit actual identifying information that would violate privacy).
(Cite GJXDM Information Exchange Package Documentation Guidelines, Hulme.)
Instance documents are XML documents containing actual, although usually fictional, data. They are the payload, or “Package,” in an information exchange. They often show the selected elements of a Subset Schema more clearly than the schema itself, especially to a non-technical audience.
Instance Documents MAY show the minimal number of elements required to validate against the collected Schemas. Instance Documents MAY also show elements that are optional in the collected Schemas. It is RECOMMENDED that a GIEPD contain both minimal Instance Documents and more fully populated examples.
Instance DocumentsMUSTvalidate though the schemas that are part of the Information Exchange Package Documentation.
1.1.7Software Tools Definition
Proprietary
Proprietary refers to software or formats in which an entity retains distribution and modification rights. Proprietary software, and particularly products produces with the software, can be difficult to use without owning a license to the producing software.
In some cases, a proprietary format because ubiquitous to the point that it is a de facto standard. In those cases, while interoperability is less of a concern, IEP documentation SHOULD be provided in neutral formats.
Proprietary may refer to a software application itself, or to a product of a software application. For example, the underlying format of a document produced with a word processor may be proprietary, independent of whether the word processor is proprietary.
Open Source
Open Source refers to a group of licenses that allow entities to distribute software while allowing others to copy and modify it. Typically, Open Source licenses require that, if an entity modifies and distributes their modifications, they must also grant the same redistribution rights. This ensures that improvements to Open Source products are returned to the development community.
Freely Available
Freely Available refers to software or services that are free to use, but are not distributed under an Open Source license.
1.1.8Additional Definitions
[Define as they appear in other sections. Someone needs to collate these.]
SSGT WantList
“The wantlist is the xml file that SSGT uses to record and maintain the state of the user's schema subset. When the user generates a schema subset package (and it is assumed that the user is finished using the SSGT), a wantlist is also generated and saved with the user's work. The wantlist is a specification for the user's schema subset and can be reloaded into SSGT to continue editing.”
(SSGT Introduction,
In short, the WantList is simply an XML-formatted list of elements and types requested for inclusion in a Subset Schema, plus any elements and types needed to support the requested ones.
2Types and Uses
Global Information Exchange Package Documentations are not technical specifications, in the usual sense. Rather, they fulfill a number of higher level functions.
2.1Samples / Project starting points
Global Information Exchange Package Documentations may act as starting points for further development. They may be used in part or in whole. The substantive information within a GIEPD may used apart from other artifacts. Alternately, information about the development process itself may be used as a base for creating additional GIEPDs.
2.2Jurisdictional Standards
Global Information Exchange Package Documentations may define jurisdictional standards. A high-level GIEPD may be further refined for sub-areas within a jurisdiction. Jurisdictions may make a GIEPD a mandatory standard.
2.3Geopolitical Standards
Global Information Exchange Package Documentations may define national or state standards. The GIEPD may be further refined, constrained, or expanded at the state or local level.
2.4Exchange Documents, Reference Documents
Global Information Exchange Package Documentations may be used to define exchanges. High-level GIEPDs are less appropriate for this role.
3Mandatory and Optional Components of a GJXDM Information Exchange Package Documentation (GIEPD)
3.1Executive Overview
GIEPDs MUST define the purpose and scope of the exchanges being described. [Add information about context]
(Will also include a table describing the manifest of required, conditional, and optional GIEP content)
3.2Process Documentation
Process documentation describes the process used in creating a particular GIEPD. This documentation MUST include:
- Description of Process Used
GIEPDsMUST list the steps involved in its development. This helps ensure that best practices were followed in the development of the GIEPD.
- Participants in the Process
GIEPDsMUST list participants in the process. Listing participants, including their affiliation and role (business, technical etc) helps ensure that a broad spectrum of participants was involved. This, in turn, ensures that the resulting GIEPD is applicable to most uses within the realm for which it was developed.
3.3Support Documentation
Supporting documentation acts as a guide to aid in the future implementation or modification of the GIEPD. This documentation can take many forms, including:
- DomainModel of business data and relationships.
(High level “business component model” (derived from the UBL definition: represents a logical grouping of components which display the basic types belonging to the IEPD) A GIEPD MAY include this high-level model [need to describe exactly what this contains (from a business viewpoint), include criteria that describes when this should be included; is not required if this information is fully described in the following section]. Models SHOULD use UML or a format readily converted to UML.
A GIEPD MUST include a detailed graphical representation of the domain model of the business data and relationships. The content of this diagram includes (describe the content of a UML document component model, using the existing specification for UML class diagrams.) [include a diagram/example here] Examples of Domain Models include [list examples, such as UML Class Diagrams or Concept Maps. (Can use any tool to create, but need to include the required pieces and standard notation)
UML Class Diagrams are STRONGLY RECOMMENDED as a consistent method for graphically depicting the domain model. They MAY be a generated artifact created from some other representational source. In this case, the UML Class Diagram MAY NOT include non-standard UML symbols and notations. Additionally, the mapping of requirements to the GJXDM, below, MAY NOT rely on any Domain Model concept or element that is not represented in standard UML notation.
UML Class Diagrams SHOULD [MUST?] include both an XML Metadata Interchange(XMI) formatted file, as well as an image file in a common open standard format such as jpeg,gif, or png.These files MUST contain only pure UML. Additional formats may also be included,such asSVG.
Alternate representations MAY be used to show business data and relationships, provided the domain model is also supplied in one of the above approved formats. Proprietary concepts MAY be included in this artifact as long as the actual mapping results are not dependent on the concepts. The mapping MUST be producible from the above approved formats alone.
- Source documents or requirements specifications.
A GIEPD MAY include source documents or requirement specifications. These materials may be actual paper documents, or some electronic equivalent. As GIEP exchanges are not limited to existing paper exchanges, there may not be existing documentation. If used, this documentation should be included in the GIEPD to help ensure adequate coverage of existing exchanges.
- Spreadsheet of business data to GJXDM component mapping
A GIEPD must contain a spreadsheet mapping business data requirements to GJXDM components.Note that a spreadsheet may be a generated artifact and not necessarily the instrument used to generate the requirements and their mappings to the GJXDM. The purpose of the spreadsheet it to make the business data requirements and mappings available in a universally readable format.
- Subset Schema Generation Tool (SSGT) Want Lists
A GIEPD MUST contain the appropriate SSGT Want List used to create its schemas. GJXDM schemas can be created by means other than the SSGT. However, in order to maintain interoperability, the related Want List is required.
3.3.1Sample Documents
Sample documents are a valuable tool to help others understand the actual data exchanged. Much of the technical material present in a GIEPD is difficult to read and understand. Sample documents can clarify the scope and details of a GIEPD.
3.3.1.1Sample Instance Documents
A GIEPD MUSTcontain at least one sample XML instance document.
XML Schema can be difficult for non-technical people to read and understand. A sample XML instance document can quickly clarify the elements defined in the XML Schema.