Skip to content

Commit

Permalink
CDM documentation to be hosted under the FINOS domain (finos#2222)
Browse files Browse the repository at this point in the history
* adding docusaurus website to cdm project

* updated lock file and docusaurus versions

* remove yarn lock file

* added md content and images

* use legacy-peer-deps=true

* fixed links

* fixing dead link and replacing isda with FINOS

* fixing dead link and replacing isda with FINOS

* fixing dead link and replacing isda with FINOS

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fixing dead link

* fix typo

* changed to primary blue and aqua

* Changes to Landing page

* Changes to Landing page

* Changes to Landing page

* Changes to Landing page

* Changes to Landing page

* updating md files

* updating md files

* updating image files

* updating image files

* updating Gihub Link

---------

Co-authored-by: maoo <[email protected]>
Co-authored-by: Maurizio Pillitu <[email protected]>
  • Loading branch information
3 people authored Jun 29, 2023
1 parent d8bf9b6 commit 7c9d93b
Showing 108 changed files with 30,989 additions and 6 deletions.
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -53,3 +53,8 @@ venv/
**/src/test/generated
/tests/cdm-sample-files/
/.metadata/

# Docusaurus website
website/.docusaurus
website/build
website/node_modules
6 changes: 0 additions & 6 deletions .project
Original file line number Diff line number Diff line change
@@ -10,11 +10,6 @@
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.pde.ManifestBuilder</name>
<arguments>
@@ -34,7 +29,6 @@
<natures>
<nature>org.eclipse.xtext.ui.shared.xtextNature</nature>
<nature>org.eclipse.m2e.core.maven2Nature</nature>
<nature>org.eclipse.jdt.core.javanature</nature>
<nature>org.eclipse.pde.PluginNature</nature>
</natures>
<filteredResources>
8 changes: 8 additions & 0 deletions docs/about-finos.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
id: about-finos
title: About FINOS, the Fintech Open Source Foundation
---

The Fintech Open Source Foundation (FINOS) is an independent 501(c)(6) nonprofit organization whose purpose is to accelerate collaboration and innovation in financial services through the adoption of open source software, standards and best practices.

Read more on https://www.finos.org/about-us
117 changes: 117 additions & 0 deletions docs/cdm-guidelines.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
---
title: CDM Java Distribution Guidelines
---

This section provides directions for downloading and using the Java
version of CDM. Topics covered are listed below:

- Prerequisites
- Introduction
- Setting Up Google's Guice Injector
- Generating Global Keys and Qualifications
- Validating the CDM instance

# Prerequisites

- Java SDK 8

# Introduction

- The CDM in Java is built using [maven](https://maven.apache.org) and is published to Maven
Central.

# Setup

In order to use the CDM in a Maven project, the following dependency
needs to be addeed to the project pom.xml:

`` ` <dependency> <groupId>org.finos.cdm</groupId> <artifactId>cdm-java</artifactId> <version>LATEST</version> </dependency> ``\`

Tutorials

![](/img/cdm-tutorials.png)

Direct link: [Tutorials](https://vimeo.com/359012532)

- The CDM model objects are classified into namespaces (cdm.base,
cdm.base.staticdata, etc). These namespaces translate into Java
packages with the same name, with each package containing a
package-info file.

![](/img/cdm-distribution.png)

- The CDM uses [builder pattern](https://en.wikipedia.org/wiki/Builder_pattern) for each of the pojos. The
distribution ships with the json to java object serialisers.

# Setting Up Google's Guice Injector

CDM uses [Google's Guice](https://github.com/google/guice) as a dependency manager. Injector is the
core of Guice that contains the whole object graph (context).

The first step is to initialise the injector. There are two options:

## Initialising the Injector, Option 1: Using provided CdmRuntimeModule

The CDM java distribution comes with a pre-built CDM module that can be
used to create an injector. It provides bindings to required classes
(ModelObjectValidator and QualifyFunctionFactory) as well as binding in
implementations for several CDM functions such as Abs, Sum

``` Java
Injector injector = Guice.createInjector(new CdmRuntimeModule()));
```

## Initialising the Injector, Option 2: Build your own Module

To build a custom injector that is not based on the CDM's runtime
module, first create a Guice module with a minimum of the two bindings
shown belows:

``` Java
public class GenericModule extends AbstractModule {

@Override
protected void configure() {
bind(ModelObjectValidator.class).to(RosettaTypeValidator.class);
bind(QualifyFunctionFactory.class).to(QualifyFunctionFactory.Default.class);
}
}
```

Once this module has been built it can be used to create the custom
injector.

``` Java
Injector injector = Guice.createInjector(new GenericModule()));
```

# Generating Global Keys and Qualifications

Within the model any data object marked with metadata key will have a
Global Key generated when that data object is populated. These Global
Keys are automatically generated using hash algorithms. The model
objects can be post-processed with Global Keys and qualified by using
the injector created in the previous step to run the code shown below:

``` Java
Contract cdmInstance = buildCdmInstance();
Contract.ContractBuilder builder = cdmInstance.toBuilder();
keyProcessor.runProcessStep(Contract.class, builder);
Contract updatedCdmInstance = builder.build();
```

# Validating the CDM instance

In order to validate the CDM instance, it is necessary to create a
RosettaTypeValidator and post process the instance as follows:

``` Java
RosettaTypeValidator validator = injector.getInstance(RosettaTypeValidator.class);
ValidationReport validationReport = validator.runProcessStep(cdmInstance.getClass(), cdmInstance.toBuilder());
if (validationReport.success()) {
List<ValidationResult<?>> validationResults = validationReport.validationFailures();
}
```

If the validation is unsuccessful then the validation results object
will contain the list of all the validation failures.
182 changes: 182 additions & 0 deletions docs/cdm-overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
---
title: Overview of the FINOS CDM
---

**Continuous Integration:** [![Codefresh build
status](https://g.codefresh.io/api/badges/pipeline/regnosysops/REGnosys%2Frosetta-cdm%2Frosetta-cdm?branch=master&key=eyJhbGciOiJIUzI1NiJ9.NWE1N2EyYTlmM2JiOTMwMDAxNDRiODMz.ZDeqVUhB-oMlbZGj4tfEiOg0cy6azXaBvoxoeidyL0g&type=cf-1)](https://g.codefresh.io/pipelines/rosetta-cdm/builds?repoOwner=REGnosys&repoName=rosetta-cdm&serviceName=REGnosys%2Frosetta-cdm&filter=trigger:build~Build;branch:master;pipeline:5a86c209eaf77d0001daacb6~rosetta-cdm)

# What is the FINOS CDM

The FINOS Common Domain Model (CDM) is a standardised, machine-readable
and machine-executable blueprint for how financial products are traded
and managed across the transaction lifecycle. It is represented as a
[domain model](https://olegchursin.medium.com/a-brief-introduction-to-domain-modeling-862a30b38353) and distributed in open source.

## Purpose

A single, digital processing standard for trade events and actions
enhances financial markets' operational efficiency in several ways:

- **Enables inter-operability and straight-through processing** across
firms, solutions and platforms, reducing the need for reconciliation
caused by variations in how each firm records trade lifecycle
events.
- **Accelerates financial technology innovation** by providing a
common, readily operational foundation for how technologies like
distributed ledger, smart contracts, cloud computing, and artificial
intelligence can be applied to financial markets.
- **Delivers better regulatory oversight**, promotes transparency and
alignment between regulators and market participants and enables
consistency in regulatory reporting, by providing a standard
representation of trade data and supporting machine executable
reporting requirements.

For further information about the CDM and its applications, please
consult the [CDM section](https://www.finos.org/common-domain-model) of the FINOS website or contact FINOS directly
at <[email protected]>.

## Design Principles

To support these objectives, the CDM is built according to a set of
design principles that include the following concepts:

- **Normalisation** through abstraction of common components
- **Composability** where objects are composed and qualified from the
bottom up
- **Mapping** to existing industry messaging formats
- **Embedded logic** to represent industry processes
- **Modularisation** into logical layers

These design principles are further detailed in the
[design-principles](#design-principles) section of the CDM
documentation.

## Governance

The CDM [governance framework](contribution#governance) regulates
the development of the CDM in open source.

## Scope

The product scope of the CDM includes OTC derivatives, cash securities,
securities financing, and commodities.

# CDM Components

**The CDM is made of three sets of components**, as laid-out in the FINOS
CDM components diagram below:

- The FINOS CDM Distribution (in *blue*)
- The Rosetta DSL (in *grey*)
- CDM Applications (in *green*)

![](/img/cdm-components-diagram.png)

## FINOS CDM Distribution

The FINOS CDM distribution is openly accessible to all industry
participants, subject to the FINOS CDM open source licence. This
distribution is fully downloadable.

The FINOS CDM distribution comprises three main sets of components:

- **Model definition**, which corresponds to the model as expressed in
the Rosetta DSL and contained into a set of *.rosetta* files
organised as *namespaces*. The primary dimensions of the model are
listed below and further described in the
[common-domain-model](/docs/common-domain-model) of the
documentation.
- Product
- Event
- Legal Agreement
- Process
- Reference Data
- Mapping (Synonym)
- **Executable code distribution**, automatically generated from the
model definitions expressed in the Rosetta DSL using [available code
generators](https://docs.rosetta-technology.io/rosetta/rosetta-dsl/rosetta-code-generators/#what-code-generators-are-available). Once a code generator is implemented for a particular
language, the corresponding code generation is included as part of
the CDM build and release process, allowing the CDM to be
automatically distributed in that language going forward.
- **Default implementation**, comprising manually-written code (in
Java) which, combined with the auto-generated code, provides a
complete implementation of the model. This hand-written code is
distributed together with the CDM to facilitate adoption by firms,
which can directly use the CDM distribution to set-up and test an
implementation. The default implementation can be used in its
original state or be disabled or extended by industry participants
in their implementations. For example, the default implementation
uses the de-facto Java hash function to support cross-referencing in
the CDM, but firms may elect to use an alternative implementation.

---
**Note:**
Only the Java executable code distribution is complete: i.e. it
represents the entire CDM as defined in Rosetta (plus any associated
default implementation). Other distributions may only capture parts of
the model: for instance, the Scala and TypeScript distributions include
the complete data model and function specifications, but not the
functions' executable code.

---

## Rosetta DSL

The CDM is written in a Domain-Specific Language (DSL) called the
*Rosetta DSL*, that comprises a [language](https://github.com/REGnosys/rosetta-dsl) (i.e. syntax, semantics and
rules) and [code generators](https://github.com/REGnosys/rosetta-code-generators).

The language includes one default code generator into [java](https://www.oracle.com/java/). To
facilitate adoption and implementation of the CDM by the community of
industry participants, the Rosetta DSL is available in open source under
an Apache 2.0 license. This allows industry participants to write and
share code generators into any other languages.

---
**Note:**
All the language components, their syntax and purpose are detailed in
the [Rosetta DSL Documentation](https://docs.rosetta-technology.io/rosetta/rosetta-dsl/rosetta-modelling-component). The documentation also describes the
mechanism to write and use code generators.

---


## CDM Applications

An ecosystem of CDM-based application components from software providers
exists in order to support the adoption of CDM and the implementation of
CDM-based production systems by industry participants. These
applications may be open source software or licensed under commercial
terms. In particular:

- Rosetta is a Software Development Kit (SDK or *dev-kit*) for the
Rosetta DSL, that provides the cumminity with a free and easy way to
contribute code to the CDM. Please refer to the [Rosetta
Documentation](https://docs.rosetta-technology.io/rosetta/rosetta-products/) for more details.

---
**Note:**
The CDM Portal and Rosetta have been developed by technology firm
[REGnosys](https://regnosys.com). FINOS encourages the adoption of CDM by software providers
but does not endorse any CDM application component.

---

# Using the CDM (Java)

The Java distribution of the CDM is designed to be built and used with
Maven.

It depends on some open source java artifacts which are freely available
from an artifact repository. Maven can be configured to use this
repository using the repository settings contained in the `settings.xml`
file in the CDM jar.

For more details, please follow the
[CDM Java Distribution Guidelines](/docs/cdm-guidelines).

---
**Note:**
These guidelines are intended as a technical documentation for
developers to make use of the Java distribution in their implementation.
---
26 changes: 26 additions & 0 deletions docs/common-domain-model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
title: The Common Domain Model
---

**There are seven modelling dimensions** to the CDM, which are detailed
in the following sections:

- [product-model](/docs/product-model)
- [event-model](/docs/event-model)
- [legal-agreements](/docs/legal-agreements)
- [process-model](/docs/process-model)
- [reference-data-model](/docs/reference-data-model)
- [mapping](/docs/mapping)
- [namespace](/docs/namespace)


In each section, selected examples of model definitions are used as
illustrations to help explain each dimension and include, where
applicable, data samples to help demonstrate the structure.

The CDM is expressed in a language called the Rosetta DSL. All the
language components used by the CDM including types, functions and
annotations are described in the [Rosetta DSL Documentation](https://docs.rosetta-technology.io/rosetta/rosetta-dsl/rosetta-modelling-component).

The complete model definition, including descriptions and other details
can be viewed in the [Textual Browser](https://portal.cdm.rosetta-technology.io/#/text-browser) in the [CDM Portal](https://portal.cdm.rosetta-technology.io).
Loading

0 comments on commit 7c9d93b

Please sign in to comment.