XML Protocols Style Guide

Style? What style?

The purpose of the style guide is to ensure that the various protocols developed have some commonality and to capture "best practices" so that the protocols remain flexible and extensible.

The example

The console logger's data will be used as an example (both positive and negative) in the following.

    <message>
      <time value="timestamp"/>
      <url value="url"/>
      <context value="context"/>
      <source value="source
        keyword"/>
      <severity value="severity keyword"/>
      <text>text</text>
    </message>

Here the source keyword names the component in Opera that generated the message. At present, these are the source keywords: "ecmascript", "java", "m2", "network", "xml", "html", "css", "xslt", "svg", "bittorrent", "voice", "gadget", and "selftest".

The rules

Break data down
Code multiple values as multiple element or attribute values if possible rather than encoding them as a single datum. Splitting data apart makes it more self-describing and easier to handle.
Enumeration values
Enumeration values should be transmitted as descriptive strings rather than as numbers (i.e., in the example, source keyword is such a value). This makes the data self-describing.
Element or attribute?
Separate data fields should generally be coded as elements, not as separate attributes on a single common element.
But simple data values could in turn be coded as values of a "value" attribute on those separate elements, as the example shows.
Attribute content should always be simple text, never base64-encoded text.
General text data
Text data should be coded as the text content of an element that carries no other attributes.
Binary data
Binary data (data containing characters that can't be represented as XML text data, even using hexadecimal coding) should be base64-encoded and placed as the text content of an element called "base64-encoded-data".
This element should never carry any attributes.
Base64-encoded data are somewhat more expensive than regular text data, and should only be used when necessary.
Element names
Element names should be descriptive: this aids protocol extensions.
The choice of "text" as the element name for the text content of the console logger message is probably suboptimal, "message-text" might have been better, or even "message".
Attribute names
The name "value" is restricted to carrying a simple text value which is to be interpreted as the value of the field which is named by the element's tag.
Attribute names should be descriptive.