EntityJSON

Complex Financial Objects and other structured data can be represented within a Symphony message as JSON data. EntityJSON is a format of JSON which is intended to facilitate interworking between different vendors.

Top Level Elements are Objects

Each element at the top level of an EntityJSON object MUST be an object, the following valid JSON objects are not valid EntityJSON because they do not meet this requirement:

{  
   "hello":[  
      1,
      2,
      3
   ]
}

{  
   "hello":"world",
   "foo":1
}

Reserved Names

The following attribute names are reserved and MUST be used with the meaning defined below:

• type
• version

All Top Level Elements are EntityJSON Objects

Every top level object in an EntityJSON document MUST be an EntityJSON Object. Fields of an EntityJSON object MAY also be objects in which case they SHOULD also be conformant EntityJSON objects. The reason for this is that this makes the data more easy to interpret and re-use. This is not strictly necessary however which is why it is not a mandatory requirement that sub-objects are valid EntityJSON objects.

EntityJSON Object

An EntityJSON Object is a JSON object which contains the following name value pairs:

type

This name MUST exist and SHOULD be the first element in the object. Its value MUST be a string containing a name in Java Package Naming convention, see https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html

version

It is inevitable that over time the need to make changes to the definitions of entities will arise. EntityJSON Objects MUST include a version identifier which SHOULD immediately follow the type and 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 an 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.

The following is an example of a valid EntityJSON document containing two EntityJSON objects, note that EntityJSON objects may be nested but all top level objects must be EntityJSON objects:

{
    "apple":
    {
        "type":     "org.symphonyoss.fin.security",
        "version":  "0.1",
        "id":
        [
            {
                "type":     "org.symphonyoss.fin.security.id.isin",
                "value":    "US0378331005"
            },
            {
                "type":     "org.symphonyoss.fin.security.id.cusip",
                "value":    "037833100"
            }
        ]
    },
	"jiraUpdated":
    {
        "type":     "com.symphony.integration.jira.event.updated" ,
        "version":  "1.0",
        "user":
        {
            "type":         "com.symphony.integration.jira.user"
            "version":      "1.0",
            "username":     "test",
            "emailAddress": "test@symphony.com",
            "displayName":  "Test User"
        },
        "labels":
        [
            "#production"
        ],
        "issue":
        {
            "type":     "com.symphony.integration.jira.issue"
            "version":  "1.0",
            "project":  "Sample 1",
            "key":      "SAM-24",
            "subject":  "Sample Bug Blocker",
            "issueType":     "Bug",
            "link":     "https://whiteam1.atlassian.net/browse/SAM-24",
            "priority": "Highest",
            "status":   "Done",
            "assignee":
            {
                "type":         "com.symphony.integration.jira.user"
                "version":      "1.0",
                "username":     "test2",
                "emailAddress": "test2@symphony.com",
                "displayName":  "Test2 User"
            },
            "changelog":
            {
                "type":     "com.symphony.integration.jira.changelog",
                "version":  "1.0",
                "change":
                [
                    {
                        "type":         "com.symphony.integration.jira.change",
                        "version":      "1.0",
                        "fieldName":    "resolution",
                        "oldValue":     "null",
                        "newValue":     "Done"
                    },
                    {
                        "type":         "com.symphony.integration.jira.change",
                        "version":      "1.0",
                        "fieldName":    "status",
                        "oldValue":     "To Do",
                        "newValue":     "Done"
                    }
                ]
            }
        }
    }
}