JSON Schema for the enterprise

This document presents the Bank Message sample application.

  1 Bank
  2 Contributing
  3 Special Thanks
  4 License

This sample is an introduction to the following JSONx technologies:

1. JSON Schema Definition Language (JSD).
2. JSONx Runtime API.

This example presents a simple schema that represents a message with a bank account number. The message can have one of three account number types: SWIFT, IBAN, and ACH. To help banking systems reduce software risk, organizations governing the SWIFT, IBAN and ACH code standards define simple test functions to determine the logical correctness of identifiers.

1. 𝒗_SWIFT(id) = regex_id( "[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?" )
2. 𝒗_IBAN (id) = regex_id( "[A-Z]{2}\d{2} ?\d{4} ?\d{4} ?\d{4} ?\d{4} ?\d{0,2}" )
3. 𝒗_ACH(id, rt) = regex_id( "\w{1,17}" ) × regex_rt( "\d{9}" )

The following schema presents a message declaration for each type of identifier with regex constraints.

  1. Create message.jsd or message.jsdx in src/test/resources/:

{
  "doc": "Schema describing bank transactions",
  "jx:ns": "http://www.jsonx.org/schema-0.4.jsd",
  "jx:schemaLocation": "http://www.jsonx.org/schema-0.4.jsd http://www.jsonx.org/schema.jsd",
  "message": { "jx:type": "object", "abstract": true },
  "swift": {
    "jx:type": "object", "extends": "message", "properties": {
      "type": { "jx:type": "string", "pattern": "swift", "nullable": false },
      "code": { "jx:type": "string", "pattern": "[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?", "nullable": false }
    }
  },
  "iban": {
    "jx:type": "object", "extends": "message", "properties": {
      "type": { "jx:type": "string", "pattern": "iban", "nullable": false },
      "code": { "jx:type": "string", "pattern": "[A-Z]{2}\\d{2} ?\\d{4} ?\\d{4} ?\\d{4} ?\\d{4} ?\\d{0,2}", "nullable": false }
    }
  },
  "ach": {
    "jx:type": "object", "extends": "message", "properties": {
      "type": { "jx:type": "string", "pattern": "ach", "nullable": false },
      "code": { "jx:type": "string", "pattern": "\\w{1,17}", "nullable": false },
      "routing": { "jx:type": "string", "pattern": "\\d{9}", "nullable": false }
    }
  }
}

<schema
  doc="Schema describing bank transactions"
  xmlns="http://www.jsonx.org/schema-0.4.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.jsonx.org/schema-0.4.xsd http://www.jsonx.org/schema.xsd">
  <object name="message" abstract="true"/>
  <object name="swift" extends="message">
    <property name="type" xsi:type="string" pattern="swift" nullable="false"/>
    <property name="code" xsi:type="string" pattern="[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?" nullable="false"/>
  </object>
  <object name="iban" extends="message">
    <property name="type" xsi:type="string" pattern="iban" nullable="false"/>
    <property name="code" xsi:type="string" pattern="[A-Z]{2}\d{2} ?\d{4} ?\d{4} ?\d{4} ?\d{4} ?\d{0,2}" nullable="false"/>
  </object>
  <object name="ach" extends="message">
    <property name="type" xsi:type="string" pattern="ach" nullable="false"/>
    <property name="code" xsi:type="string" pattern="\w{1,17}" nullable="false"/>
    <property name="routing" xsi:type="string" pattern="\d{9}" nullable="false"/>
  </object>
</schema>

_{Note: You can use the Converter utility to automatically convert between JSD and JSDx.}

  2. With the message.jsd or message.jsdx, you can use the jsonx-maven-plugin to automatically generate the Java class files. In your POM, add:

<plugin>
  <groupId>org.jsonx</groupId>
  <artifactId>jsonx-maven-plugin</artifactId>
  <version>0.4.0</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <phase>generate-test-sources</phase>
      <configuration>
        <destDir>${project.build.directory}/generated-test-sources/jsonx</destDir>
        <namespacePackages>
          <namespacePackage package="com.example.bank."/>
        </namespacePackages>
        <schemas>
          <schema>src/test/resources/message.jsd</schema> <!-- or message.jsdx -->
        </schemas>
      </configuration>
    </execution>
  </executions>
</plugin>

  3. (Alternatively) Create the Java class files by hand:

^{Note: Set-ters and get-ters have been replaced with public fields for conciseness.}

import org.jsonx.*;

public abstract class Message implements JxObject {
}

import org.jsonx.*;

public class Swift extends Message {
  @StringProperty(pattern="swift", nullable=false)
  public String type;

  @StringProperty(pattern="[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?", nullable=false)
  public String code;
}

import org.jsonx.*;

public class Iban extends Message {
  @StringProperty(pattern="iban", nullable=false)
  public String type;

  @StringProperty(pattern="[A-Z]{2}\\d{2} ?\\d{4} ?\\d{4} ?\\d{4} ?\\d{4} ?\\d{0,2}", nullable=false)
  public String code;
}

import org.jsonx.*;

public class Ach extends Message {
  @StringProperty(pattern="ach", nullable=false)
  public String type;

  @StringProperty(pattern="\\w{1,17}", nullable=false)
  public String code;

  @StringProperty(pattern="\\d{9}", nullable=false)
  public String routing;
}

  4. You can use these classes to represent Messages of type Swift, Iban, and Ach.

List<Message> messages = new ArrayList<>();

Swift swift = new Swift();
swift.setType("swift");
swift.setCode("CTBAAU2S");
messages.add(swift);

Iban iban = new Iban();
iban.setType("iban");
iban.setCode("DE91 1000 0000 0123 4567 89");
messages.add(iban);

Ach ach = new Ach();
ach.setType("ach");
ach.setCode("379272957729384");
ach.setRouting("021000021");
messages.add(ach);

  5. You can now marshal the Java objects to JSON:

for (Message message : messages) {
  String json = JxEncoder._2.marshal(message);
  System.out.println(json);
}

... will produce:

{
  "type": "swift",
  "code": "CTBAAU2S"
}
{
  "type": "iban",
  "code": "DE91 1000 0000 0123 4567 89"
}
{
  "type": "ach",
  "code": "379272957729384",
  "routing": "021000021"
}

  6. You can also parse the JSON into Java objects:

for (Message message : messages) {
  String json = JxEncoder._2.marshal(message);
  System.out.println(json);

  Message json2 = JxDecoder.parseObject(message.getClass(), json);
  assertEquals(json, json2);
}

The code included in this module implements this example.

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

_{Special thanks to EJ Technologies for providing their award winning Java Profiler (JProfiler) for development of the JSONx Framework.}

This project is licensed under the MIT License - see the LICENSE.txt file for details.