Today's industry standard for messaging is JSON.  Define your incoming and outgoing JSON messages.  

Then extract their metadata into JSONSchema definitions.

There's several similar schemes and tools, many use JSONSchema internally and layer their own superset onto it.  

1) JSONSchema is language-agnostic and platform-agnostic, an important aspect of a commercial application.   It is an agnostic specification to hand off to customers, 3rd party developers, etc, as they'll be using various languages and tools.

2) JSONSchema validation prevents bad incoming data.  Remember, customers control the incoming data and format.  Multiple by 100 customers and bad data WILL get sent.

3) Define a universal header element for all messages.  

  "type": "object",
  "$schema": "",
  "$id": "header.json",
  "title": "header",
  "description": "universal header",
  "properties": {
    "message_type": {
      "type": "string",
      "maxLength": 50
    "version": {
      "type": "string",
      "maxLength": 10
    "tracking_id": {
      "type": "integer"
    "create_date": {
      "type": "integer"
  "required": [

These properties are the bare minimum for a successful API:

  • message_type
  • version
  • tracking_id
  • create_date

4) Select a validator.   Almost all languages are available.

5) Create a suite of test messages.  Include messages which pass validation but also messages which fail - a bad message_type, a null create_date, a missing version,  etc. Verify the error handling of your application.  Run this test suite during every build and deploy.

6) JSONSchema is your System of Record.  Other artifacts such as class objects, database tables, etc. should be derived and controlled by the JSONSchemas.

AD1: Infrastructure with Cloud Formation
AD2: Messaging I/O
AD3: Abstract Factory
AD4: Database
AD5: Application Layer - Aspects
AD5: Application Layer - Canonical
AD5: Application Layer - Data Mapping
AD5: Application Layer - Protocol Adapter
AD6: Security