...
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
...
Tag | Description | Can Be Nested Within |
|---|---|---|
| <PresentationML>document<<presentationML>document</PresentationML>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><presentationML> <td><th><li> |
| <br/> | Line break | <PresentationML><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><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><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><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><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><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><presentationML> |
Named Character References
...
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: (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”>
<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 UTC with the semantics of a Java Date. |
| org.symphonyoss.type.country | An ISO 3166-1 Alpha 2 Country code (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) |
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 ISO 4217 (see https://en.wikipedia.org/wiki/ISO_4217) |
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
...
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> <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.