Babelfish CDR

Metapackage Conversion in Progress

NB: We are converting Babelfish CDR to a Metapackage with multiple components, some links might 404 at the moment

The Babelfish CDR Library is a Java based Maven artifact for the efficient processing of JSON payloads associated with the Australian Consumer Data Right (aka open banking). It provides the ability to parse, manipulate, generate and validate compliant payloads associated with the Consumer Data Standards. It is annotated with industry standard Jackson and OpenAPI (fka Swagger) annotations to enable smooth integration into downstream projects.

Babelfish CDR is currently developed and maintained by Biza.io.

We welcome discussion around the Consumer Data Right at the DataRight.io Slack Channel.

Features

• Jackson mappings for all payloads defined within the Consumer Data Standards
• On demand conversion between payload versions powered by Orika Mapper
• All enumerations defined within Consumer Data Standards with human readable descriptions for presentation layer
• Serialisation and Deserialisation to strong Java types for all Common Field Types
• Java Validation (JSR-303) rules for all required attributes, Pagination and Product & Account Components
• Fluent Builders for all payloads powered by Lombok
• OpenAPI 3 (fka Swagger) annotations for all payloads suitable and tested for Spring Framework and Springdoc
• Reasonably well tested, over 350 validation rules and nearly 300 tests (but there is always room for more!)
• Lookup and Validation for Merchant Category Codes, BSB Numbers and SWIFT Routing Codes

Quick Start

Processing an input payload and validating it is as simple as:

    ResponseBankingProductByIdV2 productResponse = new ObjectMapper().readValue(
        "{\"links\":{\"self\":\"http://localhost/cds-au/v1/banking/products/073e7e70-357d-4858-8f52-92283f4edd6f\"},\"meta\":{},"
        + "\"data\":{\"productId\":\"073e7e70-357d-4858-8f52-92283f4edd6f\",\"lastUpdated\":\"2020-02-03T06:32:27Z\","
        + "\"productCategory\":\"TRANS_AND_SAVINGS_ACCOUNTS\",\"name\":\"Example Product\",\"description\":\"Example Product Description\","
        + "\"brand\":\"ACME\",\"brandName\":\"ACME Bank\",\"isTailored\":false}}",
        ResponseBankingProductByIdV2.class);

Generating a compliant payload is as simple as:

    ResponseBankingProductByIdV2 productResponse =
        ResponseBankingProductByIdV2.builder()
            .links(LinksV1.builder().self(URI.create(
                "http://localhost/cds-au/v1/banking/products/073e7e70-357d-4858-8f52-92283f4edd6f"))
                .build())
            .meta(MetaV1.builder().build())
            .data(BankingProductDetailV2.builder().productId("073e7e70-357d-4858-8f52-92283f4edd6f")
                .lastUpdated(OffsetDateTime.now())
                .productCategory(BankingProductCategory.TRANS_AND_SAVINGS_ACCOUNTS)
                .name("Example Product").description("Example Product Description").brand("ACME")
                .tailored(false).build())
            .build();
    Set<ConstraintViolation<ResponseBankingProductByIdV2>> productResponseValidation =
        Validation.buildDefaultValidatorFactory().getValidator().validate(productResponse);
    if (productResponseValidation.isEmpty()) {
      System.out.println(new ObjectMapper().setSerializationInclusion(Include.NON_ABSENT).writeValueAsString(productResponse));
    } else {
      System.out.println(
          "Object failed validation with errors of: " + productResponseValidation.toString());
    }

Which yields:

{
   "data":{
      "productId":"073e7e70-357d-4858-8f52-92283f4edd6f",
      "lastUpdated":"2020-02-05T10:02:25.26832+11:00",
      "productCategory":"TRANS_AND_SAVINGS_ACCOUNTS",
      "name":"Example Product",
      "description":"Example Product Description",
      "brand":"ACME",
      "isTailored":false
   },
   "links":{
      "self":"http://localhost/cds-au/v1/banking/products/073e7e70-357d-4858-8f52-92283f4edd6f"
   },
   "meta":{

   }
}

Table of Contents

• Features
• Quick Start
• Usage
• Projects
• Support
• Compatibility
• Prerequisites
• Using Babelfish CDR in your project
• Extended Features
• Building
• Contributing
• License

Usage

(Back to top)

This library is available on Maven Central and therefore can be utilised by adding the following lines to your pom.xml:

<dependency>
    <groupId>io.biza</groupId>
    <artifactId>babelfish-cdr</artifactId>
    <version>1.2.4</version>
</dependency>

Projects

babelfish-cdr is utilised in a number of public projects:

• Deep Thought
• Electronic Thumb

If you are using babelfish-cdr in your project drop us an email and we will add it here.

Support

Biza Pty Ltd are currently the primary maintainers of this software.

We welcome bug reports via GitHub Issues or if you prefer via email.

If you are looking for commercial support for this library please contact us via email.

Compatibility

(Back to top)

The Babelfish CDR library tries to provide full coverage of payloads defined within the Consumer Data Standards. While we try to align our version numbers to those of the Standards unfortunately the DSB has chosen to use all of the x.y.z versioning of the semantic versioning scheme. Consequently the following table outlines the alignment between Babelfish versions and the Standards:

Prerequisites

(Back to top)

You need the following installed and available in your $PATH during compilation:

• Java 11+
• Apache Maven 3.6.3 or later

Using Babelfish CDR in your project

(Back to top)

Babelfish CDR is intended for embedding within your CDR client or server project as a Maven (or Gradle) dependency. Once it is added to your project you gain access to the ability to manipulate CDR payloads in a number of different ways.

Parse and Validate CDR Payload

(Back to top)

Parsing a sample JSON payload can be conducted using Jackson and then verified using Java Validation API:

    ResponseBankingProductByIdV2 productResponse = new ObjectMapper().readValue(
        "{\"links\":{\"self\":\"http://localhost/cds-au/v1/banking/products/073e7e70-357d-4858-8f52-92283f4edd6f\"},\"meta\":{},"
        + "\"data\":{\"productId\":\"073e7e70-357d-4858-8f52-92283f4edd6f\",\"lastUpdated\":\"2020-02-03T06:32:27Z\","
        + "\"productCategory\":\"TRANS_AND_SAVINGS_ACCOUNTS\",\"name\":\"Example Product\",\"description\":\"Example Product Description\","
        + "\"brand\":\"ACME\",\"brandName\":\"ACME Bank\",\"isTailored\":false}}",
        ResponseBankingProductByIdV2.class);
    Set<ConstraintViolation<ResponseBankingProductByIdV2>> productResponseValidation =
        Validation.buildDefaultValidatorFactory().getValidator().validate(productResponse);

Validate and Generate CDR Payload

(Back to top)

Generating a CDR Payload can be conducted using the fluent builder API within Babelfish. Additionally the payload can be validated using Java Validation API.

An example is as follows:

ResponseBankingProductByIdV2 productResponse =
        ResponseBankingProductByIdV2.builder()
            .links(LinksV1.builder().self(URI.create(
                "http://localhost/cds-au/v1/banking/products/073e7e70-357d-4858-8f52-92283f4edd6f"))
                .build())
            .meta(MetaV1.builder().build())
            .data(BankingProductDetailV2.builder().productId("073e7e70-357d-4858-8f52-92283f4edd6f")
                .lastUpdated(OffsetDateTime.now())
                .productCategory(BankingProductCategory.TRANS_AND_SAVINGS_ACCOUNTS)
                .name("Example Product").description("Example Product Description").brand("ACME")
                .tailored(false).build())
            .build();
    Set<ConstraintViolation<ResponseBankingProductByIdV2>> productResponseValidation =
        Validation.buildDefaultValidatorFactory().getValidator().validate(productResponse);
    if (productResponseValidation.isEmpty()) {
      System.out.println(new ObjectMapper().setSerializationInclusion(Include.NON_ABSENT).writeValueAsString(productResponse));
    } else {
      System.out.println(
          "Object failed validation with errors of: " + productResponseValidation.toString());
    }

Convert CDR Payload between versions

(Back to top)

Babelfish enables you to convert between two different payload versions. This means that a Data Recipient can build for a newer (or older) version of a payload while maintaining ongoing compatibility from individual Data Holders who may be ahead or behind the version expected by the Recipient. We use Orika and a set of specific mappers for each different payload version and then make it available in BabelFishConverter.

An example is as follows:

    BankingProductDetailV2 detail = BankingProductDetailV2.builder()
        .productId("073e7e70-357d-4858-8f52-92283f4edd6f").lastUpdated(OffsetDateTime.now())
        .productCategory(BankingProductCategory.TRANS_AND_SAVINGS_ACCOUNTS).name("Example Product")
        .description("Example Product Description").brand("ACME").isTailored(false).build();

    // Downgrade it to V1
    BankingProductDetailV1 downgradedDetail =
        BabelFishConverter.convert(detail, BankingProductDetailV1.class);
    // Upgrade back to V2
    BankingProductDetailV2 upgradedDetail = BabelFishConverter.convert(downgradedDetail, BankingProductDetailV2.class);

Dynamically discover what class to use for version conversion

(Back to top)

To make it easier to integrate Babelfish into upstream projects we also make available the BabelfishVersioner class. Here's an example where we hand it a BankingProductDetailV2 and ask it for the nearest version (in this case the range is only 1 <= 2):

    Class<?> destinationType = BabelfishVersioner.getVersionedClass(inputData.getClass(),
        2, 1);
    BabelfishVersioner.convert(inputData, destinationType);

This is coupled in Deep Thought to allow for dynamic payload version switching based on request parameters (in CDRVersioner).

Using in Spring

(Back to top)

We are actively using Babelfish CDR payload descriptions within Deep Thought as part of a Spring + Springdoc project. The following demonstrates the definition of a Get Product Detail endpoint:

@Operation(summary = "Get Product Detail",
      description = "Returns details product information based on the specified product identifier")
  @ApiResponses(
      value = {
          @ApiResponse(responseCode = "200", description = "Response Successful",
              content = @Content(schema = @Schema(oneOf = {ResponseBankingProductByIdV1.class,
                  ResponseBankingProductByIdV2.class}))),
          @ApiResponse(responseCode = "404",
              description = "Unable to find requested Product Identifier")})
  @GetMapping(value = "/{productId}", produces = {MediaType.APPLICATION_JSON_VALUE})
  default ResponseEntity<ResponseBankingProductByIdV2> getProductDetail(
      @NotNull @Valid @PathVariable("productId") UUID productId) {
    return getDelegate().getProductDetail(productId);
  }

Extended Features

(Back to top)

Babelfish incorporates a number of customised features to aid developers with integrating with and using the CDR payloads.

Enumeration Labels

(Back to top)

All enumerations used within Babelfish provide a human readable label available via the label() method:

    System.out.println("name: " + BankingProductCategory.TRANS_AND_SAVINGS_ACCOUNTS.name()
        + " label: " + BankingProductCategory.TRANS_AND_SAVINGS_ACCOUNTS.label());
    // Result: name: TRANS_AND_SAVINGS_ACCOUNTS label: Transaction & Savings

JSON (De)Serialisators

(Back to top)

Babelfish employs a set of StdConverter extensions to facilitate the conversion to/from Common Field Types specified within the Standards. These are embedded as @JsonSerialize and @JsonDeserialize annotations within payloads but can be used independently if desired.

The following provides a table of the converters available:

Custom Assertions

(Back to top)

Many of the payloads contain a custom javax.validation.Constraint called AssertTrueBabelfish.

AssertTrueBabelfish behaves like the default AssertTrue validation assertion but includes an additional String[] array called fields which provides information about the specific field(s) which were involved within a failure of the assertion. This annotation is used extensively for validating CDR payloads which utilise the additionalValue conditional field structure and are intended to provide human presentable error messages along with a pointer to the field(s) in question.

One such example is in BankingConstraintV1 which verifies that when a Constraint Type of MIN_BALANCE is specified the additionalValue field must be in CDS AmountString format.

Another notable example demonstrating compound reporting is within BankingProductFeeV1

  @AssertTrueBabelfish(
      message = "One of amount, balanceRate, transactionRate or accruedRate is MANDATORY",
      fields = {"amount", "balanceRate", "accruedRate", "transactionRate"})

This assertion reports a set of field names which can be highlighted but for which only one at a time is accepted.

Phone Number Parsing

(Back to top)

The CommonPhoneNumberV1 class contains a number of additional functions using Google's PhoneNumberUtil library. Most notably there is a method of setWithFullNumber which accepts a standard Australian number (for example 0733006000) and internationalises it into the requested format and fields. Use of this extension functionality is entirely optional.

Building

(Back to top)

babelfish-cdr uses Maven for compilation activies.

To build the library and install it in your local Maven cache:

1. cd babelfish-cdr
2. mvn clean install

Contributing

(Back to top)

1. Clone repository and create a new branch: $ git checkout https://github.com/bizaio/babelfish-cdr -b my_new_branch
2. Make changes (including tests please!)
3. Submit Pull Request for integration of changes

License

(Back to top)

GNU Lesser General Public License v3.0 2020 - Biza Pty Ltd. Please have a look at the LICENSE.md for more details.