Requirements

This document describes different solutions that have been investigated on behalf of the FINOS Financial Objects Working Group to:

1. Define object definitions, currently documented on this Wiki page, which includes
1. Field names
2. Field types
3. Object inheritance and peer relationships
4. Comments and documentation
2. Build a micro site that can contain:
1. General purpose documentation
2. Comments and technical docs that are extracted from object definitions
3. Generate language-specific bundles (or packages, or artifacts) for easy consumption for , ordered by priority:
1. TypeScript definitions for NodeJS
2. C# objects for .NET
3. Java Beans for Java
4. Classes for Python
4. Setup a continuous build process that allows to:
1. separate object definitions (aka source code) to language-specific bundles
2. Implement a collaboration workflow on source code using a distributed code management tool like GitHub (and Pull Requests)

Latest feedback from the Financial Objects Working Group remarked that:

1. Human readable documentation is very important
1. Discoverability, look-up and search for objects will help avoiding duplicates
2. Developers must be able to adopt it easily
3. Tooling should allow representing the stage of an object (ie approved, in review, proposed, …)
4. Agnostic from the technology/language used to adopt it

The most challenging requirement is #3, since:

1. All the others are already implemented within the FDC3 program activity, using TypeScript, TypeDoc and GitHub Pages as solution, read more on ODP Wiki page
2. There is no standard approach for “DSL for object definitions that binds into all (main) languages (mentioned above on #3)”
3. TypeScript, which is, by far, the most adopted language within FINOS for this purpose, doesn’t provide transpiling features into many other languages; there are several libraries that tackle 1:1 transformations, but none of them seem to be widely adopted or be supported by a solid open source community.

Solutions

The solution space is basically split in 2, language-driven and data-driven solutions.

Language-driven

Adopt a programming language to define objects and rely on the language compilers/transpilers to produce language-specific bindings (ie an NPM or JAR package)

1. Protocol Buffers (from Google) is a strong solution for defining objects (and implementation) that comply with RPC semantics using the strongly-typed binary data format (of protocol buffers); for this reason, generated objects and interfaces comply with a custom data format, they are not plain old objects. Another peculiarity is the lack of support for object inheritance or the removal of field optional/required from version 2 to 3. We've been playing around with some object definitions taken from the FDC3 ContextData codebase, while collecting questions that are still open for debate
   1. Which version to use? 3 or 2?
   2. Any best practice to work around inheritance absence?
   3. Style guide: does the default one suffice, or needs to be extended?
   4. Nested types: what are the use cases where nested types are better than simple composition?
2. Kotlin is a JVM-based programming language, so it’s natively compatible with Java, which provides Interop capabilities for Javascript, C, Swift and others. For Typescript, there’s a Gradle plugin that allows Typescript generation from Kotlin, although it’s maintained by a humble community (3 contributors). Kotlin is also the most trending language in 2018, with a growth of 260% on GitHub public repositories.
3. Haxe, similar to Kotlin, but with a wider support for language bindings; the downside is that there is some custom coding needed in order to bind to TypeScript, which is - by far - the most important binding to deliver

Data-driven

Define a format, using a general purpose markup language (like YAML), that allows to define object definitions (as described on #1) and build custom solution to generate site documentation and language-specific bindings.

The solution would be delivered in form of:

1. A YAML (or similar) format to define object structure, relations between objects and (fine-grained) documentation (#1)
2. A language-specific binding generation process - continuously invoked - that reads the format and generates language-specific bindings; this can be achieved in different ways:
   1. Using TypeScript as reference implementation; other language bindings will be added when requested. This approach probably doesn’t satisfy entirely requirement #3
   2. Translating YAML to JSON first, then use QuickType to generate language-specific bundles; the main objective of QuickType seems to fit well with FO requirements, but needs some further testing using real specifications and testing integration with FDC3 definitions
   3. Using language-specific libraries, for example jsonschema2pojo for Java Beans, MakeTypes for Typescript definitions and JsonCSharpClassGenerator for .NET classes
3. A YAML to HTML (or MarkDown) generation to produce documentation content