OpenBankingToolkit / openbanking-uk-datamodel

Java library generated from the UK datamodel

	Current Status
Build
Code coverage
Release
License

This repository is part of the Open Banking Tool kit. If you just landed to that repository looking for our tool kit, we recommend having a first read to https://github.com/OpenBankingToolkit/openbanking-toolkit

OpenBanking uk datamodel

A Java data model library (Generated classes from OB Swagger documentation) for Open Banking uk: https://www.openbanking.org.uk/read-write-apis/ . This project is compiled with JDK 11.

Usage

<dependency>
    <groupId>com.forgerock.openbanking.uk</groupId>
    <artifactId>openbanking-uk-datamodel</artifactId>
</dependency>

Class generation

Many of the classes are generated from the OB Swagger documentation. The project is setup to make it easy to generate the OB model classes and skeleton API classes using Maven. For efficiency, the default maven profile does not generate the code, but it is easy to do so using code-gen profile (see below).

The configuration for the swagger generation is currently within this project's main pom.xml and the swagger specification is within src/main/resources/specification.

When a new version of OB API is released, the following steps should be performed:

1. Download the Swagger yaml files from OB Spec pages (https://github.com/OpenBankingUK/read-write-api-specs/releases). As of v3.1.8, there are swagger files for Accounts, Payments, Funds Confirmation, Events and Variable Recurring Payments.

2. Place the swagger files under src/main/resources/specification (replacing existing ones where applicable).

3. Run mvn clean install -Pcode-gen

   This will generate classes into target/generated-sources/swagger

4. Check the generated files and copy them into the appropriate source folder (e.g. src/main/java).

   Note that these guidelines originally advised not to overwrite existing files, but this is flawed since OB regularly makes changes/fixes to existing classes. Therefore, it is necessary to overwrite all files and then selectively rollback the changes, depending on what's changed. This is a long and painstaking process!

   It is worth noting that a number of generated files appear to have changed significantly (e.g. OBReadConsent1 switching to OBReadConsent1Data and its new PermissionsEnum). However, it is important to compare the effect on the resulting JSON (plus any changes to the validation), as the change often makes no difference to the API, and yet the impact may be significant elsewhere (e.g. on openbanking-aspsp). As a result of this, we have not switched to OBReadConsent1Data.

   Other notable changes include things like OBEventSubscriptionResponse1Data switching from a String to a URL for the callbackUrl or httpopenbankingOrgUkrid within OBEventSubject1 being renamed to httpColonOpenbankingOrgUkRid, but the @JsonProperty annotation remaining the same. Again, neither of these make any difference to the resulting JSON, so these changes have not been applied.

   TO BE AWARE: the yaml spec used on the client to generate the source is the version spec 1.1 it means that the keys y|Y|yes|Yes|YES|n|N|no|No|NO |true|True|TRUE|false|False|FALSE |on|On|ON|off|Off|OFF will be evaluated to boolean true and false when these keys aren't enclosed in quotes. Check these keys in the yaml file to identify the classes that must be change manually to the proper key value.

5. Remove Links, Meta, OBError1 and OBErrorResponse1 - we use shared generic versions of these classes.

6. Uncomment the relevant <inputSpec> listing within the openapi-generator-maven-plugin in the pom for the next swagger spec (and repeat for each new swagger YAML file).

7. If using Intellij, run format and optimise imports on newly generated files.

8. Run build to ensure everything compiles and copyrights are generated for new source files.

9. Commit and raise PR.