FAQs
Several tools are available in the justice community to search NIEM / GJXDM. These include the National Center for State Courts (NCSC) Wayfarer tool, the Model Viewer tool built into the Subset Schema Generation Tool (SSGT), and the Excel spreadsheet included in the NIEM / GJXDM distribution.
In Wayfarer and the SSGT Model Viewer, to locate an element like Charge, simply type the element's name in the "search" text box, and click search. Both tools will show the elements that are contained within this element's type. For example, within ChargeType, one of the included elements is ChargeVictim. Clicking on the link for ChargeVictim takes the user to VictimType.
To find elements in the spreadsheet, simply use Excel's "Find..." feature. (Be sure to click the option that searches across worksheets, as the spreadsheet splits up the GJXDM into separate worksheets.) Hyperlinks embedded within the spreadsheet take the user to relevant types.
These elements are defined by the types derived from DocumentType in the GJXDM. Within the GJXDM class hierarchy, a generic DocumentType is defined. This type contains a number of metadata-like properties identified by Dublin Core, the Intel community, and records management community. The "outermost tags in instance documents" are the elements defined by the types derived from DocumentType in the JXDM.
The consistent baseline model and dictionary of reusable building blocks to create them is being designed and build by the Justice community. Furthermore, note that there are already a number of groups in existence that provide "official blessing," for example the Joint Task Force on Rap Sheet Standardization. This is also why each is allowed to reside in its own namespace (outside of JXDM) -- because undoubtedly there will be some customization (extensions to JXDM) required in many of these documents. Again unofficially, examples would be
<element name="RapSheet" type= "RapSheetType"></element>
<element name="DriverHistory" type= "DriverHistoryType"></element>
<element name="ProtectionOrder" type= "ProtectionOrderType"></element>
<element name="CourtOrder" type= "CourtOrderType"></element>
... where each "__________Type" above is derived from and therefore inherits metadata from the JXDM DocumentType.
Another more specialized example:
<element name="MNCourtOrder" type="MNCourtOrderType"></element>
... a specialization of CourtOrder for Minnesota which might be derived from the more generic CourtOrderType.
Many complex-type elements with an ID element also have a corresponding text element and/or a code element. The content of any element of type IDType is dependent on the context. Since ID is of type TextType, the actual identifier could be a name or a number. One can use the ID element, the text element, or both, depending on the business need. For example, for the case where one would like to use JurisdictionID with ID = 10, and to send “Maricopa” as the textual translation for that ID. So, one could decide to use for either a name or a number, depending on how one identifies the jurisdiction districts in the information sharing enterprise. If the problem is that one wants to include both the name and the number of the district in the jurisdiction, then could be used for the number and
for the name (instead of adding an element to IDType for the name).
is defined as "A district in a jurisdiction." Another alternative is to use a code. The use case referred to here would often be solved with a code; in the enumeration the value would be "10" and the documentation (presumably available to sender and receiver) would be "Maricopa". For this example, adding a local extension something like (with a corresponding enumeration) would work. The advantage of this method is that ties the code to its description in the schema (so you won't have a conflict if is "Maricopa" but is "9"). The disadvantage of this method is that you are not actually sending the name (the receiving system must refer to the enumeration schema), and in this case you have to extend the GJXDM.
GJXDM and NIEM add a great deal of redundancy to element names to provide a set of data element names that are relatively complete, semantically precise, and globally understood. The meaning of any given tagname should be determinable within a variety of circumstances, ranging from well-structured documents with rich context to transaction or message-oriented formats that may be weak in context.
To do this the XML Structure Task Force prohibits synonyms, and uses ISO/IEC Standard 11179 (Specification and Standardization of Data Elements) syntax for naming elements consistently and precisely. The resulting data dictionary will have potentially wide applicability and a larger scope, but the expense will be longer names. Furthermore, we used the Draft Federal XML Developer's Guide 2002: which states that ISO 11179 naming syntax should be used for XML element names.
XML Developer's Guide: http://xml.fido.gov/documents/in_progress/developersguide.pdf
The Global Justice XML Data Dictionary schema employs the following rules for rendering elements vs. attributes:
(1) Employ elements whenever possible. Attributes are used as the exception, and only with reasonable justification based on XML limitations or significant avoidance of complexity. Justification: Elements are much more flexible than attributes. Attributes cannot be complex and cannot occur multiple times. Federal guidelines and best practices suggest the avoidance of attribute use.
(2) SuperType properties are always attributes. Justification: The SuperType contains properties that are applicable to all components of the GJXDM. Therefore, all fields will include the properties of SuperType. All GJXDM components are derived from SuperType, so that all components inherit all the SuperType properties. At the same time, SuperType has neither complex nor simple content. In fact, it has no content; it's empty. Thus, objects with simple content can still be derived from SuperType, because it cannot contain any subordinate elements. And finally, one can consider SuperType properties generic enough to be metadata (such as, probabilityNumeric, distributionText, reportedDate, expirationDate, etc.) on all GJXDM components.
(3) DocumentType properties are always elements. Reason: In view of rule (1), a justification is unnecessary. However, we provide the following explanation because of the special nature of DocumentType as the root of all reference document types. DocumentType is derived from SuperType. In the GJXDM, reference document types derived from DocumentType are the primary basis for information exchange transactions. As such, DocumentType has a set of metadata properties that are common to all documents derived from it. We render these properties as elements for several reasons: • There is no need for DocumentType to be empty (as there is for SuperType). • Metadata defined for DocumentType is fairly complex and cannot easily be rendered as attributes. • The common properties of many documents and transactions will likely be extended and evolve. • What may be metadata in a library or relational table sense is relevant document data to somebody.
(4) Use attributes for metadata that simply qualify the format or representation of a data value, but are not a required part of that data value, and when such use will avoid complexity. Justification: Sometimes metadata qualifiers are not an essential part of the data itself. The data can stand alone and still be understood, or in other words, the qualifiers can be ignored without harm to understanding. The qualifier simply clarifies or focuses the meaning of the data or its representation. Furthermore, use of attributes for such qualifiers avoids unnecessary content complexity. Example:
<PersonGivenName namevariant= "initial">M</PersonGivenName>
5) Properties of simple numeric types are attributes. Justification: Type Measure, Numeric, Quantity, Rate, and several other types that require qualifiers such as unit of measure or tolerance will be handled with attributes to maintain simple content. These qualifiers are simple and have stable values. The data value and qualifiers cannot be separated without almost total loss of meaning. Furthermore, use of attributes for such qualifiers avoids unnecessary content complexity. Example:
<VehicleSpeedMeasure speedunit="mph" tolerance= "5">37</VehicleSpeedMeasure>
6) Mixed content is NOT supported. Justification: Mixed content models are confusing and extremely difficult to implement and parse. Example:
<VehicleSpeedMeasure>37
<SpeedUnit>mph</SpeedUnit>
</VehicleSpeedMeasure>
The capability to store common names (context data elements) in the dictionary database that are not used in the Globa Justice XML Data Dictionary (GJXDD) schema will be added. These context elements will be defined and will refer (link) to the Global Justice XML Data Model (GJXDM) elements that represent them in a given context. For example, ArrestDate will be defined in the dictionary, and its entry will reference (link to) ActivityDate and explain the Arrest context. This capability will assist users who must map their local dictionaries to GJXDM.
There are a number of ways to identify appropriate context data elements. The XSTF is evaluating them. The capability to have and use context data elements for navigation of GJXDM is available with the first release of the GJXDM Search Tool. However, identifying what context data elements should be contained in the GJXDM database will be evolutionary and based upon input from the field and methods for collecting such. Also, by design, synonymous elements are not permitted in the GJXDD. However, data element definitions may contain synonyms that will not appear as tags in the GJXDD schema. Thus, within the documentation it is easy to discover synonyms by searching. A data registry for the GJXDM would also enable this.
In addition, the National Center for State Courts Wayfarer GJXDM search tool ("Wayfarer") has a "contextual search" feature that can often identify context data elements.
Wayfarer: http://apps.ncsc.org/niem/
GJXDM and NIEM are reference models. Elements are designed for maximum initial flexibility.
They are:
Overly inclusive — there are more elements than necessary for many applications.
Optional — minoccurs= "0"
Unrestricted — maxoccurs="unbounded"
These rules are not absolute. There may be cases in which these rules are not practical or realistic, or where the XML Schema specifications must take precedence. In addition the reference architectures define a constraint schema in which more specific constraints can be applied to elements.
In dynamic type substitution, the structure that contains the new element remains unmodified. When constructing an instance, the structure of a derived type may be substituted for an expected type structure. The original remains the same. The only requirements to using type substitution are that the name of the type to substitute must be specified as the value of attribute "xsi:type," an attribute of the original element, and only derived types may be substituted. (For example, SubjectType may be substituted for PersonType, but VehicleType may not be substituted.)
In static element replacement, the element substitution is done in the schema, rather than the instance. This requires extending types all the way up the containment hierarchy to the root of the schema. (While this does result in a larger number of derived types in the extension schema, it has the advantage of making the element replacements explicit in the schema.) To make the element replacement explicit, it is recommended that the schema designer include documentation in the schema indicating the name of the element being replaced. The "appinfo" namespace included in GJXDM and NIEM provide an element suited for this purpose.
Both dynamic type substitution and static element replacement have advantages and disadvantages.
The dynamic type substitution has distinct advantages.
o The main advantage of dynamic type substitution is that it achieves the desired element replacement without requiring definition of as many derived types in the extension schema.
o Another advantage of dynamic type substitution is keeping the original element name and path. Even if other users don't understand your local “CourtOrderNarrative” extension, they can still process the original "CourtActivityCourtOrder" because it has the same name and same path as expected.
However, dynamic type substitution also has several disadvantages.
o The complete definition of the containing types is unknown until instances are created.
o The schema designer has to describe where type substitution is required in a non-schema artifact, which makes it difficult to use the schema as the basis for exchange.
o Many common XML tools and messaging infrastructure do not support type substitution in some instances.
The advantages and disadvantages of static element replacement are the opposite of dynamic type substitution. Static element replacement results in more derived types in the extension schema and enjoys broader infrastructure support. However, the schema can be used as a more complete definition of the IEP structure, making the semantics clear and explicit.
What are the guidelines for using elements vs. attributes?
The following guidelines are extracted or paraphrased from the Draft Federal XML Developer's Guide (April 2002).
Use elements that extend easily for maximum flexibility, and use attributes to reduce complexities or when forced to maintain simple content.
One of the key schema design decisions is whether to represent an information element as an XML element or attribute. Once an information item has been made an attribute, it cannot be extended further. There cannot be multiple uses of it within the same element (i.e. 0 or 1, but no more). Also, if enumerated, an attribute cannot be extended to add values to its enumeration list.
Unfortunately, some of these guidelines can be very subjective. For example, what constitutes metadata and what constitutes data? Often this depends upon the user perspective and the application. For a model with very large applicability and a requirement for maximum flexibility, it is probably safer to use elements that can be more easily extended. Using attributes may prevent unnecessary complexities or when forced to maintain simple content.
Attributes SHOULD:
Only be used to convey metadata that will not be parsed. In other words, attribute values should be single words or numeric, not lists of words or numbers that may require further parsing.
Provide metadata that describes the entire content of an element. If the element has children, any attributes should be generally applicable to all the children.
Provide extra metadata required to better understand the business value of an element.
Be short, preferably numbers or conforming to the XML Name Token convention.
Only be used to describe information units that cannot or will not be further extended or subdivided.
Attributes SHOULD NOT contain long string values.
For these reasons and to promote uniformity, Federal guidelines discourage the use of attributes. But if you must use them, keep them simple.
“DocumentType” is derived from “SuperType”. In the GJXDM, reference document types derived from “DocumentType” are the primary basis for information exchange transactions. As such, “DocumentType” has a set of metadata properties that are common to all documents derived from it.
We render these properties as elements for several reasons:
There is no need for “DocumentType” to be empty (as there is for “SuperType”).
Metadata defined for “DocumentType” is fairly complex and cannot easily be rendered as attributes.
The common properties of many documents and transactions will likely be extended and evolve.
What may be metadata in a library or relational table sense is relevant document data to others.
A complete list that details all of the deprecated elements and other changes can be found in the change log at the following page:
The GJXDM element j:PersonModusOperandi is of type j:ActivityType, and can be used to describe "A methodology of action, particularly a criminal action, known to be routinely associated with a persons crimes."
Content Elements:
Content elements enclose data. The following is an example:
<Person s:id="A">
...
<PersonName>
<PersonFullName>Adam Smith</PersonFullName>
</PersonName>
...
</Person>
In this example, there is a person object. The person contains an element called PersonName. The PersonName element contains an element called PersonFullName. The PersonFullName element contains a string Adam Smith. The PersonFullName element is obviously a content-containing element. It has
the person’s name (a literal string) as its content.
The PersonName is also a content-containing element, as its content represents the person name, as a structured object. It contains the element PersonFullName, and could contain additional elements.
Reference Elements:
Reference elements do not enclose content. Instead, they reference content as external objects:
<Incident>
<ActivityDate>2003-10-02</ActivityDate>
...
<IncidentSeizedPropertyRef s:ref="C"/>
...
</Incident>
In the above example, the property that was seized as part of the incident is referenced out to another object, an XML object in the same XML instance, with the identifier C.
<Property s:id="C">
<PropertyDescriptionText>
White microwave oven
</PropertyDescriptionText>
<PropertyTypeCode>HOVEN</PropertyTypeCode>
<PropertyMakeName>Kenmore</PropertyMakeName>
<PropertyModelName>63292</PropertyModelName>
</Property>
The object that has the identifier C is an instance of Property, specifically representing a microwave oven. The reasons for representing the microwave oven
outside of the incident should be quite evident: it is its own object, independent of the incident. It has its own life cycle. If the incident did not exist, the microwave oven would still exist.
The seized property is an element of the incident because it is a fixed part of the incident. The incident involved the seizing of the property, and that will not change. However, the incident should be a reference element, as the property has its own life cycle, outside of the incident.
Abstract elements are elements defined in XML schema but cannot appear in an XML instance; this is an XML schema mechanism for forcing substitution. Substitution groups must be used whenever abstract elements are defined; an element that is a member of the abstract element’s substitution group must appear in place of the abstract element in an XML instance.
NIEM uses abstract elements as the head-element for all substitution groups. Abstract elements are used throughout the NIEM wherever there is a concept that can be represented multiple ways. An abstract element serves as a placeholder in the reference model, but it must be substituted when creating an exchange specification.
Below is a snippet of NIEM schema to illustrate this.
<xsd:complexType name="PersonType">
<xsd:complexContent>
<xsd:extension base="u:SuperType">
<xsd:sequence>
<xsd:element ref="u:PersonSex" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="PersonSex" abstract="true"/>
<xsd:element name="PersonSexText" type="u:TextType" substitutionGroup="u:PersonSex" / >
<xsd:element name="PersonSexCode" type="ncic:SEXCodeType" substitutionGroup="u:PersonSex" / >
In the example above both PersonSexText and PersonSexCode belong to the PersonSex substitution group. This means either PersonSexText or PersonSexCode must replace PersonSex whenever PersonType is instantiated.