FAQs
Context Data Elements are components that have common names because they are all attributes of the same object through inheritance. It is crucial to first understand the concept of inheritance of properties from more general types to more specific types to understand context data elements.
The easiest way to understand the concept of inheritance in GJXDM and NIEM is through the following example. One very general object (high level type) is ActivityType. There are a number of more specific objects derived from ActivityType, such as ArrestType and BookingType. All three aforementioned complex types have a number of properties (XML elements) that compose them. One property of ActivityType is ActivityDate (the date an activity occurred). Since ArrestType and BookingType are derived from ActivityType, they are considered more specific Activity objects with a number of specialized properties of their own. However, they each inherit all the properties of their parent, ActivityType. One property inherited by both ArrestType and BookingType from ActivityType is ActivityDate.
Now suppose you want to determine how to tag (in XML) an ArrestDate. If you search the GJXDM or NIEM schema for ArrestDate, you will not find one. The reason is that the value of an arrest date would be tagged as ActivityDate inside of the ArrestType. Analogously, a BookingDate would also be tagged as an ActivityDate as a property of BookingType. This is because the date of any specific activity derived from ActivityType inherits ActivityDate.
GJXDM and NIEM are object-oriented models that take advantage of property inheritance to reuse components. This helps to keep the total number of elements smaller. However, this also means that some specific data element names do not exist in the dictionary because more generically named properties are inherited down to the more specific subtypes.
During analysis of the data requirements sources, the XML Structure Task Force (XSTF) found no evidence of the neccesity for mandatory use of date and time together. Many sources had defined both date and time components, but there were no components of the type DateTime.
The XML Schema DateTime type uses ISO 8601 format and does not permit the option to use either date or time without the other. This means that if a component is of type DateTime, then both date and time are significant and must be present. As a result, there is no way to indicate that time is insignificant or unknown. The XSTF believes that this could lead to potentially confusing or misleading data. Therefore, it was decided to use xsd:date and xsd:time should be used optionally and independently.
Bail and court ordered fines are not child properties of Case (they are not part of CaseType or inherited from ActivityType). However, there is a Bail property (of BailType, extends ActivityType), and a FinancialObligation property (of FinancialObligationType, extends ObligationType) that could be used for the court ordered fines.
In the XML Schema for this exchange, one should consider making the root an extension of the DocumentType specific to this exchange. For example, one could define an element SummaryCase and an associated complex type SummaryCaseType (which extends DocumentType). This helps indicate SummaryCase is the root of the XML document and allows the Document metadata (in DocumentType) to be used.
If there is only one case per document instance, then one can simply define SummaryCaseType to include j:Case, j:Bail, and j:FinancialObligation in their entirety. The fact that they are all together in the same SummaryCase indicates they are related. It is also possible to use a GJXDM subset schema to exclude the elements in j:Case, j:Bail, and j:FinancialObligation that are not needed.
Or, instead of including j:Bail and j:FinancialObligation in their entirety, it is possible to just include selected properties (if there are only a few of them). Alternatively (and especially if you can have more than one case per document instance). Then one could define a local CaseType as an extension of j:CaseType. In the local CaseType, j:Bail and j:FinancialObligation can be included in their entirety or just the selected properties from these that are necessary . SummaryCase would contain only j:Case. In the XML document instance one would use type substitution to substitute the local CaseType (e.g.). In the Amber Alert example in the Developer Workshop materials there is an example of how this is done - some missing person and contact properties were included in a local IncidentType that extends the j:IncidentType.
It is important to note that type substitution can be more difficult to handle on the receive end in some architectures. Instead of type substitution, it is possible to just define a local Case property with your local CaseType as described above. Finally, one could also consider using references if your case can have multiple defendants and you need to relate bail amounts or fine amounts with particular defendants. Lets say, defendant 'x' information is specified in Case. In CaseDefendantParty.Person, it would be neccesary specify j:id='x'. In Bail, BailSubjectReference (instead of BailSubject) with j:ref='x' would be used.
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: