Question: What is the intended use for BrowserTypes.Convert

[Roaders]

Question Area

• [ ] App Directory
• [x] API
• [ ] Context Data
• [ ] Intents
• [ ] Use Cases
• [ ] Other

Question

I had always thought that the Convert class in BrowserTypes was for serializing and desterilizing messages to strings for passing them across the boundary between apps. I just realised that doesn't really make sense though as we are able to pass whole objects across the channel api and we don't need to convert them to strings.

I now assume that the expectation is that we pass objects and not strings?

I don't remember seeing any mention of the Convert class in the protocol docs. I am now wondering what expected use for it is? If it's just something we get for free from the conversion code then that's fine. I just want to make sure I'm not missing something.

[kriswest]

Hi @Roaders, The convert class is automatically generated by QuickType - I'd refer you to the docs for it, but there are few. There is this article which explains the use case in other languages such as C# (Conversion of String types to stronger types): http://blog.quicktype.io/transformed-string-types/

The type conversion is not as relevant in JS/TS, but it does (for example) convert string dates to the Date class.

A further use case is that the convert class asserts the type of data converted to a JSON string or of a JSON string converted to the generated type objects, outputting a human-readable error message describing an error that broke conversion. This is valuable when doing conversions at runtime and when working with other codebases (which might be handing you invalid objects, which TypeScript will not help you detect or debug at runtime).

It is perhaps something we could add some docs on... Any suggestions for where in the docs to do that?

[Roaders]

The point about dates is a very good one. What does the spec say about how to transfer dates across the boundary.

IMHO the best way to deal with this would be convert all messages to strings using the Convert class before sending them over the boundary. This would validate the types and convert dates. The only issue is that if one implementor does this and other don't the implementations would not be compatible.

How does @robmoffat 's implementation deal with dates?

[kriswest]

The format of dates in the message meta elements is governed by the Timestamp schema in common.schema.json: https://github.com/finos/FDC3/blob/001b6ccb55a907b1100c8ba8320f66c15de4f655/schemas/api/common.schema.json#L33

That defines the string format using the date-time string format from JSON schema (Which is basically ISO 8601): https://json-schema.org/understanding-json-schema/reference/string#dates-and-times. That of course works fine with the JavaScript Date class.

The context part of the FDC3 standard uses essentially the same format, referencing ISO 8601 again: https://fdc3.finos.org/docs/context/spec#times. However, contexts embedded into the messages will not be turned into Date types (I think) as the context schemas are not used directly I imagine.

I've not reviewed Rob's code in detail yet, but I would guess that he's not using the convert class to parse messages, but I have seen the types used to govern messages produced. @robmoffat to confirm.

[Roaders]

ok, thanks Kris. That answers the question. Dates are correctly handled by the spec. I hadn't come across any usage of dates in my implementation so far so didn't know how they were specified.