What are the rules for rendering elements vs. attributes in GJXDM?

The Global Justice XML Data Model (GJXDM) 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:

  1. There is no need for “DocumentType” to be empty (as there is for “SuperType”).
  2. Metadata defined for “DocumentType” is fairly complex and cannot easily be rendered as attributes.
  3. The common properties of many documents and transactions will likely be extended and evolve.
  4. 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:

<PersonName personNameTypeCode="aka"/>
  1. 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>

 

NOTE: The rules above will require modifications to: “PropertyStatusType”, “PropertyStatusCode”, “DrivingJurisdictionAuthorityCode”, and “IDType” – reconsider the design and replace attributes with elements, if possible, as “IDType” is overused.  In addition, use a complex type with complex content to simplify the derivatives.  For example, “DriversLicense” requires more structure than a number (e.g. issuing state, date, etc.); and should be captured in elements not attributes.