X-Messages Specification 1.0
Namespace Document 1 December 2010
- This version:
- http://www.xmessages.org/specification
- Latest version:
- http://www.xmessages.org/specification
- Author:
This work is licensed under a Creative Commons Attribution License. This copyright applies to the X-Messages Specification and accompanying documentation. Regarding underlying technology, X-Messages uses the Hyper-Text Transfer Protocol (HTTP), an open Internet protocol that can be freely used by anyone.
Abstract
This specification describes the X-Messages HTTP header and its format, defined as a JSON encoded data structure.
Status of this Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This is the first version of the X-Messages specification. It is produced as an authoritative documentation of the status and use of the X-Messages HTTP header.
This document assumes the reader has knowledge of and a basic understanding of the HyperText Transfer Protocol (HTTP) and the JavaScript Object Notation (JSON) data-interchange format.
It proposes a standard method for transporting messages from a server to client over HTTP in an ubobtrusive manner. These messages notify the user of the result of actions performed or provide system feedback.
See the changes section for details of the changes in this version of the specification.
Table of Contents
1. Introduction
Nearly all user interfaces in web based applications have a messaging system which notifies the user of the result of actions performed. However, there is no standard way of communicating these messages, the types of messages displayed, or a common messaging format used to send these messages from the server to a client. As a result, users encounter different message formats and styles between using applications, sometimes even producing human error upon incorrectly interpreting these notifications.
Another problem is found by developers themselves where, unless using a framework which provides a user notification method, they are usually left with the task to develope a method for transporting messages to the client. Most have a format they have defined over the years that they reuse between projects, however no method currently exists which addresses this issue.
The X-Messages specification attempts to provide a standard solution to these problems by defining a clear and coherent method for transporting messages from the server to a client.
2. Header Format
The X-Messages header is a list of lists. The beginning and ending of each list MUST BE defined using the open bracket "[" AND the close bracket "]" respectively. Each message list within the parent messages list represents a message, and each list within the parent messages list MUST BE separated by a comma (,).
X-Messages: [ [ String message, Integer type, Integer timestamp, Mixed custom ], [ ... ] ]
Each message list CAN contain up to 4 positions, within a MINIMUM of 1 required position. Each position within a message list MUST BE separated by a comma (,). The X-Messages header CANNOT contain new lines "LF" OR carridge returns "CR".
-
Message
[String]The message to display, encapsulated in single OR double quotes (required always) -
Type
[Integer]The type of the message (see Message Types) -
Timestamp
[Integer]The unix timestamp of the message creation -
Custom
[Mixed]A custom data which can be represented as aString
The message position SHOULD always be converted to a String if its of any other data type. To omit a position from a message list, the position AND all following positions MUST BE omitted, or a Null value MUST BE used as the position value. Be aware that 0 is a valid message type, unix timestamp, and custom data value.
The parent messages list MAY contain an UNLIMITED number of individual message lists. Keep in mind however, that although the HTTP specification does not define a limit on the size of headers, most HTTP servers do impose a maximum length.
Developers writing scripts to parse the X-Messages header SHOULD consider the optional nature of the message type, unix timestamp and custom position in the message list. As default values, it is recommended to consider the following:
-
Type SHOULD default to
0 - Timestamp SHOULD default to the current unix timestamp at the server
-
Custom SHOULD default to
Null
If there is no message, the message list is empty OR the message contains only single space characters it SHOULD be discarded. The absence of the X-Messages header OR an empty header value OR an empty messages list SHOULD be considered as there not existing any messages to display.
3. Message Types
There are 5 defined message types. Each message type is represented with an Integer value from 0 to 4. Additionally, each message type has a recommended color to use (where color formatting is relevant) to present the message to the user:
-
Custom
[0]An application specific notification (no predefined color) -
Info
[1]An informative message or notification (blue) -
Confirm
[2]A message confirming a user action was successful (green) -
Warning
[3]A message warning of a problem encountered during a process (yellow) -
Error
[4]A message alerting that a user action failed (red)
Acknowledgments
It is worth mentioning that the X-Messages format was designed and created using open source software, namely Linux (Fedora), gedit and Mozilla Firefox with the Firebug extension.
Changes
- Current version reflects no changes
