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.