...
- The Originating User composes the message and decides who to send it to.
- One or more Apps may be invoked to provide UI support to compose structured complex objects included in the message. These are known as Composing Apps, and they are responsible for constructing messages as defined by this document.
- The Originating User Agent takes the constructed message and submits it for delivery to the intended user. The User Agent is also responsible for validating messages and may reject them if they are invalid, and for encrypting messages on behalf of the Originating User. Examples of User Agents are the Symphony Web UI, the Symphony iOS Client App, and the API Agent process.
- The Symphony Service is responsible for the physical storage, transmission and delivery to the Receiving User Agent.
- The Receiving User Agent is responsible for validating received messages and informing the Receiving User of any errors in the structure of received messages, and for selecting appropriate Apps to render complex structured objects included in received messages.
- One or more Apps may be invoked to enrich complex objects contained in the message. The enrichment Apps may add to, but may not delete or change, the representation of the complex entities.
- One or more Apps may be invoked to render included complex structured objects in the message. These are known as Rendering Apps and they are responsible for rendering complex structured objects in several formats.
...
Receiving User Agents MUST apply these rules so that Rendering Apps are not faced with badly formed messages and that faulty Composing Apps are not able to inject badly formed messages into the system.
...
Versioning
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 MessageMLIt is inevitable that over time the need to make changes to the definitions of entities will arise. Complex entities include a version identifier which MUST contain a two level semantic version number of the form Major.Minor where major and minor are decimal integer values. At initialization time each App can register a list of entity type IDs and versions which it is able to render. When registering a type ID the App MUST be capable of displaying entities of the specified type up to and including the specified version and all prior versions.
When selecting an App to render a particular complex entity the system will consider all Apps which have registered the type identifier of the entity and whose version capability has a major version number which is greater than or equal to the version of the received entity. For example if an entity of version 2.2 is received and App which registers its ability to handle that type at version 2.1 would be eligible to handle the entity but one which registers itself at version 1.9 would not.
Where optional attributes are added to an existing entity definition and all existing instances of such entities would continue to a) be valid and b) have the same meaning when interpreted under the expanded definition, then the minor version number of the entity definition should be incremented. In other cases the major version number of the entity definition must be incremented.
The major version number 0 may be used in cases where an entity definition is under initial development. At the point where an entity definition is intended for production use it should be assigned a major version of at least 1.
Character Encoding
All PresentationML documents MUST be encoded in UTF-8.
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
- 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. |
<MessageML>
<p><b><i><td><th><li>
<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.
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
EntityML is a markup for describing Complex Financial Objects and other complex structured entities (Entities) within a message. Entities are composed and rendered by Apps within the Symphony platform, and may be constructed from multiple sub-entities and attributes by composition.
Overall Structure
Entities are built up from a number of sub-Entities and Attributes[1]. Entities may contain structured content whereas attributes contain only a single value, and an entity may exist directly in a message, whereas an attribute may only exist as a child of an entity. Entities and Attributes are defined to have a name and a type. In the event that the name is not specified it has the same value as the type. In cases where an Entity definition has only one sub-Entity or Attribute of a given type, it may be unnamed (taking the type as its name).
When a name is specified in an Entity definition, the name MUST NOT contain any period characters (‘.’). Because all format identifiers contain period marks (see below), this guarantees that a defined name will not collide with an inferred one.
Where two or more Attributes within a single Entity have the same name, Composing Apps MUST:
- Attach an XML-attribute named “priority” with an integer value in the range 0 to 255 to each Attribute.
- Ensure that exactly one such Attribute has the priority value 0.
Composing Apps SHOULD ensure that the priority value for each Attribute within a single parent Entity is unique amongst Attributes with the same name in the same parent Entity. There is no specific intention to limit the maximum number of Attributes with a given name for a single entity to 256 although it is unclear if there is any real use case for such an example. Originators MAY therefore specify multiple id elements with the same, non-zero priority.
Composing Apps MUST NOT generate multiple sub-Entities within a single entity with the same name.
Originating User Agents MUST reject all badly formed messages, including those which fail to comply with the restrictions on Attributes and sub-Entities defined above.
Receiving User Agents who receive an Entity with multiple sub-entities having the same name and type MUST interpret these as if the multiple sub-entities were combined.
Receiving User Agents who receive an Entity with multiple sub-Entities having the same name and different types MUST ignore the second and subsequent occurrences of that named sub-Entity.
Receiving User Agents who receive an entity with multiple attributes having the same name and type MUST ignore the second and subsequent occurrences of that named attribute.
Receiving User Agents who receive an entity with multiple attributes having the same name which do not have priority values defined MUST assign the priority value zero to the first such attribute (unless there is another such Attribute which has the priority value zero specified) and assign the priority value 255 to all other such attributes.
Receiving User Agents who receive an entity with multiple attributes having the same name and the priority value zero MUST assign the priority value one to the second and subsequent such attributes.
For example the following badly formed entity
...
| <p>text</p> | Paragraph, contains text to be rendered as a single block of text. | <presentationML> <td><th><li> |
| <br/> | Line break | <presentationML> <i><b> <p><ol><ul> <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> |
| <chime/> | An audible chime. A message MAY contain a single <chime/> tag, messages SHOULD NOT contain multiple chime tags but if such messages are received the recipient MUST treat this in the same was as if there was only one <chime/>. The position of the <chime/> tag is not significant. | <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
EntityML
EntityML is a markup for describing Complex Financial Objects and other complex structured entities (Entities) within a message. Entities are composed and rendered by Apps within the Symphony platform, and may be constructed from multiple sub-entities and attributes by composition.
Overall Structure
Entities are built up from a number of sub-Entities and Attributes[1]. Entities may contain structured content whereas attributes contain only a single value, and an entity may exist directly in a message, whereas an attribute may only exist as a child of an entity. Entities and Attributes are defined to have a name and a type. In the event that the name is not specified it has the same value as the type. In cases where an Entity definition has only one sub-Entity or Attribute of a given type, it may be unnamed (taking the type as its name).
When a name is specified in an Entity definition, the name MUST NOT contain any period characters (‘.’). Because all format identifiers contain period marks (see below), this guarantees that a defined name will not collide with an inferred one.
Where two or more Attributes within a single Entity have the same name, Composing Apps MUST:
- Attach an XML-attribute named “priority” with an integer value in the range 0 to 127 to each Attribute.
- Ensure that exactly one such Attribute has the priority value 0.
Composing Apps SHOULD ensure that the priority value for each Attribute within a single parent Entity is unique amongst Attributes with the same name in the same parent Entity. There is no specific intention to limit the maximum number of Attributes with a given name for a single entity to 256 although it is unclear if there is any real use case for such an example. Originators MAY therefore specify multiple id elements with the same, non-zero priority.
Composing Apps MUST NOT generate multiple sub-Entities within a single entity with the same name.
Originating User Agents MUST reject all badly formed messages, including those which fail to comply with the restrictions on Attributes and sub-Entities defined above.
Receiving User Agents who receive an Entity with multiple sub-entities having the same name and type MUST interpret these as if the multiple sub-entities were combined.
Receiving User Agents who receive an Entity with multiple sub-Entities having the same name and different types MUST ignore the second and subsequent occurrences of that named sub-Entity.
Receiving User Agents who receive an entity with multiple attributes having the same name and type MUST ignore the second and subsequent occurrences of that named attribute.
Receiving User Agents who receive an entity with multiple attributes having the same name which do not have priority values defined MUST assign the priority value zero to the first such attribute (unless there is another such Attribute which has the priority value zero specified) and assign the priority value 127 to all other such attributes.
Receiving User Agents who receive an entity with multiple attributes having the same name and the priority value zero MUST assign the priority value one to the second and subsequent such attributes.
For example the following badly formed entity
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security.price” version="1.0"/> <entity type=”org.symphonyoss.fin.security” version="1.1"/> <attribute <attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip”isin” priority=10 value=”459200-10-1””US0378331005”/> <attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi”cusip” priority=21 value=”BBG000B9XRY4””037833100”/> </entity> </entity> |
MUST be interpreted by Receiving User Agents as if it was
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security.price”/> <entity type=”org.symphonyoss.fin.security”security” version="1.2"/> <attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/> <attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” priority=1 value=”037833100””459200-10-1”/> <attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi” priority=2 value=”BBG000B9XRY4”/> </entity> </entity> |
MUST be interpreted by Receiving User Agents as if it was
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security. |
Type Identifiers
Type identifiers follow Java package naming conventions, and are derived from DNS domain names. Only the organization which owns a domain in the DNS may define types with identifiers beginning with that name. The namespace org.symphonyoss is reserved by the Symphony Foundation for agreed standard type definitions. The namespace org.symphonyoss.fin is reserved for standard complex financial objects to be defined and agreed by the Complex Financial Objects Working Group.
Until the establishment of other Working Groups to cover other parts of the overall org.symphonyoss namespace, the Complex Financial Objects Working Group will define appropriate general formats in that namespace, subject to approval by the Symphony Foundation Engineering Steering Committee (ESCo).
Attribute Priorities
The lack of globally recognized identifiers for some entities such as financial securities, and the existence of multiple widely understood identifiers for the same entity (such as ISIN, CUSIP and OpenFIGI) means that it is necessary to be able to express multiple identifiers for the same entity. The intention is that in cases where more than one identifier is given that the id values stated are equivalent and that they refer to the same entity. It would be an error, for example, to specify an entity with a CUSIP for Apple and an ISIN for Oracle.
Where multiple well known identifiers exist for a particular Entity type, the Entity format definition SHOULD permits the presence of multiple attributes with the same name to hold the potentially multiple identifiers for the same Entity.
Originators SHOULD generate id elements for all identifiers they are aware of for the entity described, for the benefit of receivers who may be unable to interpret some identifier types.
Where an Attribute has a priority, it MUST have an integer value in the range 0 to 255. The priority describes the order of preference or reliability of the given value in the eyes of the message originator, with lower values indicating a preference over higher values, an identifier with a priority of 0 is the most preferred or reliable and one with a priority of 255 is the least preferred.
Within a single entity element where there are id elements present, there MUST be exactly one id element with a priority value of zero. This SHOULD be the identifier that the originator uses as the primary key for the entity being described.
Each id element SHOULD have a priority value which is unique among id elements in the same entity element.
Rendering Apps SHOULD use the identifier with the lowest priority which they are able to interpret.
Composing Apps MUST NOT generate entities with multiple identifiers which refer to different entities.
Default Representation
Any Entity element MAY contain a single presentationML element which contains a default representation of the described Entity in PresentationML markup. This rendering is a default presentation for use by receivers who are unable to understand the structured data in the entity markup and MUST NOT contain any information which is not included in, or derivable from data included in the structured data in the entity. Where present, the presentationML element of an entity MUST contain a representation of the entity which is consistent with the structured data contained within the entity.
Any entity element which is not contained within another entity element MUST contain a presentationML entity containing a default representation of the element for the benefit of receivers who are unable to decode the structured data in the entity.
Receivers MAY ignore the presentationML element of any entity and SHOULD do so if they are able to fully interpret the structured data content of the element.
EntityML Tags
EntityML contains the following tags:
Tag | Description | Can Be Nested Within |
<entity type=”type.id” name=”entity.name”> <attribute>…..</attribute> <entity>…..</entity> <presentationML> default representation </presentationML> </entity> | An Entity describes some type of complex object which is referenced from within a message. All Entity elements MUST include a type XML-attribute which defines the format and semantics of the Entity. All Entity elements MAY contain child Entity and Attribute elements which are considered to make up the Entity by composition. All Entity elements MAY contain a presentationML element which contains a default representation of the Entity in PresentationML mark up. Entity elements which are not children of another entity element MUST contain a presentationML element. | <messageML> <p><b><i><td><th><li> <entity> |
<attribute type=”type.id” name=”attribute.name” priority=”preference” value=”value.string” /> | An Attribute describes an attribute of a complex object. All Attribute elements MUST include a type XML-attribute which defines the format and semantics of the Attribute. All Attribute elements MUST contain a value XML-attribute which defines the value of the Attribute. Where there are multiple Attributes within an Entity with the same name a priority XML-attribute MUST be present, indicating which value is preferred. | <entity> |
Attribute Types
The following type identifiers are defined for Attributes:
Type ID | Description |
org.symphonyoss.number.byte | An 8 bit unsigned integer, having the semantics of a Java byte, represented as a string of decimal digits. |
org.symphonyoss.number.short | A 16 bit signed integer, having the semantics of a Java short, represented as a string of decimal digits. |
org.symphonyoss.number.int | A 32 bit signed integer, having the semantics of a Java int, represented as a string of decimal digits. |
org.symphonyoss.number.long | A 64 bit signed integer, having the semantics of a Java long, represented as a string of decimal digits. |
org.symphonyoss.number.double | A 64 bit signed floating point number, having the semantics of a Java double, represented as a string of decimal digits optionally with a single decimal point. |
org.symphonyoss.type.string | A string value. |
org.symphonyoss.time.millis | A date/time value specified as a 64 bit integer value, represented as a string of decimal digits, indicating a time in milliseconds since Jan 1st 1970 with the semantics of a Java Date. |
org.symphonyoss.fin.security.id.isin | An International Securities Identification Number (see https://en.wikipedia.org/wiki/International_Securities_Identification_Number) |
org.symphonyoss.fin.security.id.cusip | A CUSIP (see https://en.wikipedia.org/wiki/CUSIP) |
org.symphonyoss.fin.security.id.openfigi | An OpenFIGI identifier (see https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier) |
org.symphonyoss.fin.exchange.id.mic | A Market Identifier Code (see http://www.iso15022.org/MIC/homepageMIC.htm) |
org.symphonyoss.fin.exchange.id.ticker | An exchange identifier |
org.symphonyoss.fin.ccy | A 3 letter currency identifier as defined in TBD |
org.symphonyoss.fin.ccypair | A 6 letter currency pair identifier as defined in TBD |
Entity Types
The following Entity Type Identifiers are defined and may have the sub-Entities and Attributes defined in the following tables.
Financial Security - org.symphonyoss.fin.security
A financial security, defined by the following Attributes
Name | Type | Cardinality | Description |
Name | 1..n | An established identifier for the security referred to. |
Example
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” priority=1 value=”037833100”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi” priority=2 value=”BBG000B9XRY4”/>
</entity> |
Price Source – org.symphonyoss.fin.price.source
A source of prices for financial securities (possibly an exchange), defined by the following Attributes
Name | Type | Cardinality | Description |
Name | 1..n | An established identifier for an exchange. |
Example
| Code Block |
|---|
<entity format=”org.symphonyoss.fin.price.source”/>
<attribute name=”id” format=”org.symphonyoss.fin.exchange.id.mic” priority=0 value=”45”/>
<attribute name=”id” format=”org.symphonyoss.fin.exchange.id.ticker” priority=1 value=”NYSE”/>
</entity> |
Moment in Time – org.symphonyoss.time.moment
A moment in time defined by the following Attributes
Name | Type | Cardinality | Description |
at | org.symphonyoss.time.millis | 1 | The moment in time. |
annotation | org.symphonyoss.type.string | 0..1 | A textual annotation. |
Example
| Code Block |
|---|
<entity format=”org.symphonyoss.time.moment”/>
<attribute name=”at” format=”org.symphonyoss.time.millis” value=45464996/>
<attribute name=”annotation” format=”org.symphonyoss.type.string” value=”Looks like it has turned here”/>
</entity> |
Period of Time – org.symphonyoss.time.range
A period time defined by the following Attributes
Name | Type | Cardinality | Description |
from | org.symphonyoss.time.millis | 1 | The start of the period of time (inclusive). |
to | org.symphonyoss.time.millis | 1 | The end of the period of time (inclusive). |
annotation | org.symphonyoss.type.string | 0..1 | A textual annotation. |
Example
| Code Block |
|---|
<entity name=”time” format=”org.symphonyoss.time.range”/>
<attribute name=”from” format=”org.symphonyoss.time.millis” value=45464646/>
<attribute name=”to” format=”org.symphonyoss.time.millis” value=45464996/>
<attribute name=”annotation” format=”org.symphonyoss.type.string” value=”Period of interest.”/>
</entity> |
Price History – org.symphonyoss.fin.security.price.history
A price of some financial security over some period time defined by the following sub-Entities
Name | Type | Cardinality | Description |
| org.symphonyoss.fin.security | 1 | The security to which this price history relates |
| org.symphonyoss.fin.price.source | 0..1 | The source of prices quoted or referred to |
time | org.symphonyoss.time.* | 1 | The moment in time or time period to which this price history relates |
| org.symphonyoss.time.moment | 0..1 | Other moments in time of interest, presumed to include annotations |
Example
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security.price.history”/>
<entity type=”org.symphonyoss.fin.security”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” priority=1 value=”037833100”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi” priority=2 value=”BBG000B9XRY4”/>
<presentationML>Apple Common Stock</presentationML>
</entity>
<entity format=”org.symphonyoss.fin.price.source”/>
<attribute name=”id” format=”org.symphonyoss.fin.exchange.id.mic” priority=0 value=”45”/>
<attribute name=”id” format=”org.symphonyoss.fin.exchange.id.ticker” priority=1 value=”NYSE”/>
<presentationML><b>NYSE</b></presentationML>
</entity>
<entity name=”time” format=”org.symphonyoss.time.range”/>
<attribute name=”from” format=”org.symphonyoss.time.millis” value=45464646/>
<attribute name=”to” format=”org.symphonyoss.time.millis” value=45464996/>
</entity>
<entity format=”org.symphonyoss.time.moment”/>
<attribute name=”at” format=”org.symphonyoss.time.millis” value=45464996/>
<attribute name=”annotation” format=”org.symphonyoss.type.string” value=”Looks like it has turned here”/>
</entity>
<presentationML>
<b>NYSE:Apple</b> from Jan 5 2016 to Mar 29 2016; at Mar 27 2016 ”Looks like it has turned here”
</presentationML>
</entity> |
Price Quote – org.symphonyoss.fin.security.price.quote
A quoted price of some financial security defined by the following Attributes and sub-Entities
Name | Type | Cardinality | Description |
| org.symphonyoss.fin.security | 1 | The security to which this price history relates |
| org.symphonyoss.fin.price.source | 0..1 | The source of prices quoted or referred to |
| org.symphonyoss.time.moment | 1 | The date/time of this price quote |
| org.symphonyoss.fin.ccy | 1 | The currency of the quoted price |
amount | org.symphonyoss.number.* | 1 | The quoted price in the given currency |
validUntil | org.symphonyoss.time.millis | 0..1 | The time until which this quote is valid |
quantityMin | org.symphonyoss.number.* | 0..1 | The minimum quantity for which the quoted price is valid |
quantityMax | org.symphonyoss.number.* | 0..1 | The maximum quantity for which the quoted price is valid |
Example
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security.price.quote”/>
<entity type=”org.symphonyoss.fin.security”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” priority=1 value=”037833100”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi” priority=2 value=”BBG000B9XRY4”/>
<presentationML>Apple Common Stock</presentationML>
</entity>
<entity format=”org.symphonyoss.fin.price.source”/>
<attribute name=”id” format=”org.symphonyoss.fin.exchange.id.mic” priority=0 value=”45”/>
<attribute name=”id” format=”org.symphonyoss.fin.exchange.id.ticker” priority=1 value=”NYSE”/>
<presentationML><b>NYSE</b></presentationML>
</entity>
<entity format=”org.symphonyoss.time.moment”/>
<attribute name=”at” format=”org.symphonyoss.time.millis” value=45464996/>
<attribute name=”annotation” format=”org.symphonyoss.type.string” value=”Looks like a value buying opportunity”/>
</entity>
<attribute format=”org.symphonyoss.fin.ccy” value=”USD”/>
<attribute name=”amount” format=”org.symphonyoss.number.double” value=”50.22123”/>
<attribute name=”validUntil” format=”org.symphonyoss.time.millis” value=45469996/>
<attribute name=”quantityMin” format=”org.symphonyoss.number.int” value=”10000”/>
<attribute name=”quantityMax” format=”org.symphonyoss.number.int” value=”99999”/>
<presentationML>
<b>NYSE:Apple</b> at Mar 27 2016; $152.07 ”Looks like a value buying opportunity”
valid until Mar 27 2016 17:00
</presentationML>
</entity> |
price” version="1.0"/>
<entity type=”org.symphonyoss.fin.security” version="1.1"/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” priority=1 value=”037833100”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi” priority=2 value=”BBG000B9XRY4”/>
</entity>
</entity> |
In this example none of the entities or attributes in the main or outermost entity is named, so their names default to their type identifiers. The second sub-entity which has the same name as the first is therefore merged with it. This means that there are now two attributes with the type ID org.symphonyoss.fin.security.id.cusip and the second (and any subsequent) occurrence is ignored.
When merging entities the version identifier and any other XML attributes which may be defined, MUST be taken from the first occurrence, in this case the version of the merged sub-entity is 1.1 since that was the version of the first occurrence in the received message. This could result in attributes being present in the merged entity which are not defined by the final version of that entity, but it is considered more important that there is predictable consistent behavior than it would be to attempt to create something valid from what is in any event an invalid input.
Type Identifiers
Type identifiers follow Java package naming conventions, and are derived from DNS domain names. Only the organization which owns a domain in the DNS may define types with identifiers beginning with that name. The namespace org.symphonyoss is reserved by the Symphony Foundation for agreed standard type definitions. The namespace org.symphonyoss.fin is reserved for standard complex financial objects to be defined and agreed by the Complex Financial Objects Working Group.
Until the establishment of other Working Groups to cover other parts of the overall org.symphonyoss namespace, the Complex Financial Objects Working Group will define appropriate general formats in that namespace, subject to approval by the Symphony Foundation Engineering Steering Committee (ESCo).
Attribute Priorities
The lack of globally recognized identifiers for some entities such as financial securities, and the existence of multiple widely understood identifiers for the same entity (such as ISIN, CUSIP and OpenFIGI) means that it is necessary to be able to express multiple identifiers for the same entity. The intention is that in cases where more than one identifier is given that the id values stated are equivalent and that they refer to the same entity. It would be an error, for example, to specify an entity with a CUSIP for Apple and an ISIN for Oracle.
Where multiple well known identifiers exist for a particular Entity type, the Entity format definition SHOULD permit the presence of multiple attributes with the same name to hold the potentially multiple identifiers for the same Entity.
Originators SHOULD generate id elements for all identifiers they are aware of for the entity described, for the benefit of receivers who may be unable to interpret some identifier types.
Where an Attribute has a priority, it MUST have an integer value in the range 0 to 127. The priority describes the order of preference or reliability of the given value in the eyes of the message originator, with lower values indicating a preference over higher values, an identifier with a priority of 0 is the most preferred or reliable and one with a priority of 127 is the least preferred.
Within a single entity element where there are id elements present, there MUST be exactly one id element with a priority value of zero. This SHOULD be the identifier that the originator uses as the primary key for the entity being described.
Each id element SHOULD have a priority value which is unique among id elements in the same entity element. There is no intention to limit the total number of identifiers provided to 127 or any other number, this is why duplicate non-zero priorities are permitted.
Rendering Apps SHOULD use the identifier with the lowest priority which they are able to interpret. In the event that there are multiple identifiers with the same priority value which are the best available option for a rendering app it SHOULD use the identifier which appears first in the markup.
Composing Apps MUST NOT generate entities with multiple identifiers which refer to different entities.
Attribute Enrichment
Attributes and the default presentation may be added or updated by an enrichment application after receipt and before being rendered. This enrichment may be used in the routing logic to decide which App is selected to render the entity and may also be used by the rendering App to produce the final on-screen representation of the entity. Enriching Apps are not permitted to remove any of the content of the received entity but may replace attributes or the default presentation by providing an addition element with the same name and ID and with an XML attribute called enrichment which contains a sequence number starting at 1. In the event that there are multiple enrichment applications and more than one enrichment App wishes to update a single attribute then the attributes added by later Apps will have higher enrichment values than those added by earlier Apps and these will be taken in preference by the rendering App when it is eventually called.
For example the following Entity could be received:
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security” version="1.0"/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<presentationML>Apple</presentationML>
</entity> |
After enrichment an additional identifier and two additional unnamed attributes might be added. These additions are all identified with the XML attribute enrichment="1":
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security” version="1.0"/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” enrichment="1" value=”037833100”/>
<attribute type="org.symphonyoss.fin.region" enrichment="1" value="NA"/>
<attribute type="org.symphonyoss.type.country" enrichment="1" value="US"/>
<presentationML>Apple</presentationML>
<presentationML enrichment="1">Apple common stock</presentationML>
</entity> |
After enrichment by a second enrichment App a further identifier and two further additional unnamed attributes might be added. These additions are all identified with the XML attribute enrichment="2":
| Code Block |
|---|
<entity type=”org.symphonyoss.fin.security” version="1.0"/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.isin” priority=0 value=”US0378331005”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.cusip” enrichment="1" value=”037833100”/>
<attribute name=”id” type=”org.symphonyoss.fin.security.id.openfigi” enrichment="2" value=”BBG000B9XRY4”/>
<attribute type="org.symphonyoss.fin.region" enrichment="1" value="NA"/>
<attribute type="org.symphonyoss.type.country" enrichment="1" value="US"/>
<attribute type="com.example.fin.tier" enrichment="2" value="BlueChip"/>
<attribute type="com.example.fin.sector" enrichment="2" value="Tech"/>
<presentationML>Apple</presentationML>
<presentationML enrichment="1">Apple common stock</presentationML>
<presentationML enrichment="2"><b>Apple</b> common stock, traded on NYSE</presentationML>
</entity> |
Note that in this case the enrichment Apps have both added extra attributes named id, which if present in the original entity would have required priority attributes to order them. The enrichment added attributes are all considered to come after all attributes of the same name in the original entity, and the enrichment added attributes are then taken in descending order or enrichment value. In the example above the openfigi ID would be treaded as if it had a priority of 2 and the cusip would be treated as if it had a priority of 3.
Default Representation
Any Entity element MAY contain a single presentationML element which contains a default representation of the described Entity in PresentationML markup. This rendering is a default presentation for use by receivers who are unable to understand the structured data in the entity markup and MUST NOT contain any information which is not included in, or derivable from data included in the structured data in the entity. Where present, the presentationML element of an entity MUST contain a representation of the entity which is consistent with the structured data contained within the entity.
Any entity element which is not contained within another entity element MUST contain a presentationML entity containing a default representation of the element for the benefit of receivers who are unable to decode the structured data in the entity.
Receivers MAY ignore the presentationML element of any entity and SHOULD do so if they are able to fully interpret the structured data content of the element.
EntityML Tags
EntityML contains the following tags: (additional syntax is described in Rendering Pipeline which is not yet included here, TBD)
Tag | Description | Can Be Nested Within |
<entity type=”type.id” name=”entity.name” version="major.minor" enrichment="positive-integer"> <attribute>…..</attribute> <entity>…..</entity> <presentationML enrichment="positive-integer"> default representation </presentationML enrichment="positive-integer"> </entity> | An Entity describes some type of complex object which is referenced from within a message. All Entity elements MUST include a type XML-attribute which defines the format and semantics of the Entity. All Entity elements MAY contain child Entity and Attribute elements which are considered to make up the Entity by composition. All Entity elements MAY contain a presentationML element which contains a default representation of the Entity in PresentationML mark up. Entity elements which are not children of another entity element MUST contain a presentationML element. | <messageML> <p><b><i><td><th><li> <entity> |
<attribute type=”type.id” name=”attribute.name” priority=”non-negative-integer” enrichment="positive-integer" value=”value.string” /> | An Attribute describes an attribute of a complex object. All Attribute elements MUST include a type XML-attribute which defines the format and semantics of the Attribute. All Attribute elements MUST contain a value XML-attribute which defines the value of the Attribute. Where there are multiple Attributes within an Entity with the same name a priority XML-attribute MUST be present, indicating which value is preferred. Priority and enrichment MUST NOT both be specified on a single attribute. Recipients of messages where this is the case MUST ignore the priority. When a renderer is presented with an entity with multiple attributes with the same name they SHOULD use the value with the lowest priority value which they can understand. If there is no such value then they SHOULD select the value with the highest enrichment value which they can understand. | <entity> |
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. | |
<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> and all EntityML tags are also valid MessageML tags, and have the same meaning as defined above. This means that all PresentationML tags can be nested within <messageML>
Entity and Attribute Definitions
The definitions of entity and attribute types have moved to Entity Definitions.
[1] In this document Entity and Attribute refer to XML Elements named “entity” and “attribute” respectively. Where we need to refer to an XML Attribute (a name value pair defined inside an XML element tag) we use the term XML-attribute.