Clarify that Context types are defined in JSON and may be handled differently in specific API bindings

[kriswest]

Enhancement Request

As identified in the discussion on #1479, the Context Part of the FDC3 standard defines the JSON encoding of Context objects, which is (in JS and .NET so far) translated into a set of types defined for that language, which may change the type of specific fields to an idiomatic type for that language (for example Date fields in JSON are string encoded according to ISO 8601-1:2019, while in JavaScript/TypeScript the Date type is used, which stringifies to the same format).

The Context overview should:

• include content explaining the difference between the JSON definitions and definitions for a specific languages API binding.
• include language-specific details on field type conventions (if they differ by language binding - e.g. dates and times).
• link to source code and packages for language-specific bindings for context types.

@hellosmithy @bingenito @kemerava

[Roaders]

My concern around this was based on the fact that the Desktop Agent Communication Protocol specifies that the messages passed between a DA and a Desktop Agent Proxy should be json objects. In our (Morgan Stanley) implementation and in the reference implementation we accomplish this by just passing the message object to the postMessage function on the MessagePort. In pretty much every case this will be absolutely fine. Dates should be passed across without issue (without being turned into a string).

This just happens magically though. We are relying on the browser to correctly serialise and deserialise the objects. It should be noted that the Dates are not converted into an ISO string. I think that they are just transfered over as the time value (ms since epoch).

I feel that we should probably clarify what exactly is passed between a desktop agent and a proxy. Is just passing the message object to messagePort.postMessage() ok? Should we iterate over the entire deep object and covert any dates into ISO strings (I don't think so).

I think what is giving me this doubt / concern is that the Convert class that is automatically generated from the types is at no point used by either implementation. It is implied (in my opinion) that this is how we are supposed to send messages over the wire (I might be incorrect here but I have always thought that this is the correct way to do it). I am pretty sure that it's been mentioned in meetings that the Convert class is the best way to ensure that the messages that we are passing around are in the correct format.

The thing is if we do use the Convert functions in one DA then it will be unable to communicate with the reference DA or the finos supplied getAgent function. They will all be speaking in structurally cloned javascript obejcts but the DA that uses Convert will be speaking in javascript object converted to string.

Sending a string over the wire is different to sending a structurally cloned javascript object.