MessageML Format for Complex Financial Objects

MessageML is a markup for representing messages including formatting (bold, italic, numbered and unnumbered lists etc.) which is used by the existing Symphony Agent API. Complex Financial Objects will be represented as entities in MessageML markup. This page describes both the current PresentationML and MessageML formats as well as the proposed EntityML extensions to support the representation of complex financial objects.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

MessageML messages are transmitted over the Symphony platform and may be composed either by the integral Symphony Rich Text Editor or by an installed application.

When received these messages will be rendered either by the integral Symphony rendering engine or by an installed application.

The sending and receiving users may have a different set of applications installed (or no applications installed) and may have different preferences of which installed application to use to compose and render messages of any particular type. It is therefore necessary that different applications, developed independently of each other MUST be capable of generating and interpreting MessageML in a consistent and predictable way.

When a message author expresses formatting for a message this should be done in a semantic rather than a presentational way. For example, the message author may say that there is a paragraph break in a message but it is up to the renderer to decide precisely how that should be rendered, e.g. whether the space between the end of one paragraph and the next should be 2 pixels or 15 pixels. In an ideal world we would want to mark up messages to indicate emphasis in a presentationally neutral way for example by referring to a word being "emphasized" as opposed to being "bold" or "italic".

However, the existing rich text editor provides buttons labelled as bold and italic and users are familiar with these terms as ways of editing a message. We will therefore treat bold and italic as semantic formatting, even though these terms express a presentational concept.

PresentationML

PresentationML is a markup language to express semantic presentation of messages in a domain agnostic way. PresentationML allows the message author to describe how the message should be presented in a semantic way by marking up text to be presented as

Bold
Italic
Paragraph Break
Line Break
Numbered List
Unnumbered list
Clickable URL
Simple html style tables.

No specific guarantee will be made about the graphical presentation of these elements which may vary from device to device and from user to user.

All valid PresentationML will be valid HTML and valid XML without modification. This means that API consumers will be able to parse PresentationML content with an XML parser and the UI will be able to display it as HTML with a CSS style sheet, although validation of received markup is necessary to ensure that malicious HTML has not been inserted by an untrustworthy message originator.

EntityML is a markup to allow for the representation of arbitrary embedded entities. All valid EntityML is valid XML.

MessageML is the combination of PresentationML and EntityML. All valid MessageML is also valid XML which means that API consumers can treat MessageML content as XML and parse it with an XML parser. Messages transmitted over Symphony APIs will be in MessageML format.

All EntityML is required to provide a default rendering expressed either as PresentationML (or plain text, which is itself valid PresentationML). In the event that no renderer for a particular EntityML expression can be found then this default rendering will be used. A renderer to present PresentationML as plain text will be provided for use by content export and other consumers requiring unformatted messages.

The Symphony platform currently stores messages in a different format, but conversion functions exist to map messages in the current storage format to MessageML and vice versa. In the future we envisage that messages will be stored directly in MessageML.

The following tags are defined for PresentationML, tag names are case sensitive:

Tag	Description	Can Be Nested Within
<PresentationML>document</PresentationML>	A PresentationML document, not stored, considered to wrap the stored PresentationML data implicitly, i.e. this tag is not written.
<p>text</p>	Paragraph, contains text to be rendered as a single block of text.	<PresentationML> <td><th><li>
<b>text</b>	Bold, contains text to be rendered in an emphasized way, by presentation as a bold font if possible.	<PresentationML> <i> <p><ol><ul> <td><th><li>
<i>text</i>	Italic, contains text to be rendered in a (secondary) emphasized way, by presentation as an italic font if possible.	<PresentationML> <b> <p><ol><ul> <td><th><li>
<ul><li>List Item 1<li/><li>List Item 1<li/></ul>	Unordered list, should be rendered as bullet points if possible.	<PresentationML> <p><b><i> <td><th><li>
<ol><li>List Item 1<li/><li>List Item 1<li/></ol>	Ordered list, should be rendered as a numbered list possible.	<PresentationML> <p><b><i> <td><th><li>
<table> <tr><th>Col 1</th><th>Col 2</th></tr> <tr><td>Cell 1,1</td><td>Cel 2,1</td></tr> </table>	Simple table.	<PresentationML> <p>
<a url="http://some.url">text<a/> <a url="http://some.url"/>	Hyperlink.	<PresentationML> <p><b><i> <td><th><li>
<chime/>	An audible chime message. A message MAY contain a single <chime/> tag, in which case it MUST contain no other content. Conversely a message which contains any other content MUST NOT contain any <chime/> tag. This is a limitation of the current implementation which may or may not change in the future.	<PresentationML>

Named Character References

PresentationML special characters can be escaped using HTML named character references. < > and & should be used to escape < > and &. The set of supported entities is as defined in http://www.w3.org/TR/html5/syntax.html#named-character-references

MessageML

The following tags are defined for MessageML, tag names are case sensitive:

Tag	Description	Can Be Nested Within
<MessageML>document</MessageML>	A MessageML document.
<hash tag="label"/>	A hashtag, equivalent to entering #label in the GUI.	<MessageML> <p><b><i><td><th><li>
<cash tag="label"/>	A cashtag, equivalent to entering $label in the GUI.	<MessageML> <p><b><i><td><th><li>
<errors> <error>Some error message</error> <error>Another error message</error> </errors>	A structure to allow for the reporting of errors in transformations. These tags should only be produced as a result of generating MessageML via transformation from another format. When generating MessageML as part of a read operation, the generating system MAY include a single <errors> section to indicate problems which occurred during processing. When sending MessageML as part of a write request the sending system SHOULD NOT generate an <errors> section. If such a section is received by the server fulfilling a write operation then the operation MUST fail.	<MessageML>

Additionally all PresentationML tags except for <PresentationML></PresentationML> are also valid MessageML tags, and have the same meaning as defined above. This means that all PresentationML tags can be nested within <MessageML>

EntityML

The following tags are defined for EntityML, tag names are case sensitive:

Tag

Description

Can Be Nested Within

</format>

PresentationML

</entity>

A custom entity with one or more entity formats and a default rendering expressed in PresentationML.

Following the opening <entity> tag there MUST be one or more <format> tags. Each <format> tag MUST have a type attribute which contains a format identifier in Java package name format. Only the owner of the equivalent domain in DNS should define that ID.

Each format tag MAY then have any number of additional attributes, but each attribute name MUST be unique within that tag.

Each format tag MAY contain an arbitrary set of sub-tags, each of which MAY have zero or more attributes and further sub tags.

Only tags may be contained within a <format> tag, text content outside of an attribute MUST NOT appear within a <format> tag.

Format tags are listed in descending order of preference, when displaying an entity the formats will be checked in order and the first format for which a valid renderer exists will be used and all other formats will be ignored. In the event that multiple renderers exist for the same format then the presentation engine will select its preferred renderer according to its own rules.

Finally after all <format> tags there SHOULD be a sequence of valid PresentationML tags which represent the default presentation in the event that no appropriate renderer for any provided format can be found.