MessageML V2 Draft Proposal

This Document is a Draft for Discussion and is subject to unlimited review and revision.

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. A draft proposal to add EntityML extensions to support the representation of complex financial objects is described at MessageML Format for Complex Financial Objects and has been partially implemented to support certain horizontal app integrations, but is not currently supported for customer use.

On the basis of experience gained with these implementations a number of suggestions have been made to make the use of these capabilities easier and to expand the set of presentation markup which is supported. This page describes a proposal for an improved MessageML which is intended to be fully implemented and supported for customer use. This implementation will include changing the internal storage format for messages in Symphony to remove limitations currently imposed by the current use of markdown as a storage format.

This proposal is intended to make it possible for third parties to create and render rich content messages without the need to implement an application renderer. Programmatic renderers will only be necessary to implement interactive capabilities or to display additional data from external sources.

One significant change in this proposal is the representation of the data for complex objects in JSON rather than XML. This facilitates the representation of somewhat more complex data structures and is a more natural fit for applications such as integrations with web enabled services which typically provide data in JSON format over a REST API.

The presentation markup of MessageML, called PresentationML, will be re-framed as a strict subset of HTML5, all PresentationML documents will be strictly valid HTML5, although not all valid HTML documents are acceptable PresentationML messages. These two changes taken together mean that a consumer of messages which is not aware of structured objects can ignore the JSON element of the message and render the PresentationML part of the message in isolation and withe semantically valid results.

The API Agent will accept full MessageML, which is a superset of PresentationML and includes a number of convenience markup structures including template macros.

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.