Schema creation and validation tips

PlatformHub plugins can send/receive messages or publish/subscribe events. Schema files are useful to determine what type of data on a certain message/event payload contains and how we can cross-check if two plugins communicate over the right type info. Therefore, every message/event should contain a schema file, even if it does not send and accept any data at all.

Here are some tips to consider when generating schema files:

Schema Tools

• Schema files can be created manually as well as by various web sites to generate schema from a given json sample. However, due to support versions of schema validators, they are all not compatible each other. We advise JSON Schema Validator and Generator) which supports JSON Schema draft-07. Once you prepare a sample json, you can easily generate relevant schema, or vice-versa. A note here as that generated schema could contain more properties information than the validator expects such as $id, pattern, default or title. To keep schema structure lean and simple, defining type property only would be enough for most cases. See example below:

{
  "type": "object",
  "properties": {
    "accountName": {
      "type": "string",
      // optional properties below
      "title": "a title",
      "$id": "an id",
      "pattern": "a pattern",
      "default": "default value for string"
    }
  }
}

• Once the schema is ready, you can test the sample payload json to verify if it is valid against the schema and covers all cases in terms of data structure.
• Schema generators do not produce information such as "additionalProperties": true, so please don't forget to add it manually after each object definition. As javascript is a dynamically typed language, this property makes sure that payload only accepts fields defined in the schema.
• The "required" property should define a list of properties an object has and are mandatory. If you define an optional type in your data class, please make sure it does not go into this list.

    internal data class Account(
        val accountName: String,
        val accountNumber: String,
        val accountDescription: String?
    )

{
  "type": "object",
  "properties": {
    "accountName": {
      "type": "string"
    },
    "accountNumber": {
      "type": "string"
    },
    "accountDescription": {
      "type": "string"
    }
  },
  "required": ["accountName", "accountNumber"],
  "additionalProperties": false
}

Please see sample app for more examples.

Addressing Compile Time Validation Errors

• Once host app includes all required plugins in build process, a validation script as part of the release process is executed to make sure all plugins contain valid schema files.

• Naming schemas is an essential part of schema generation, because schema validation script can locate schemas based on policy definitions for the message/event they belong respectively. If the naming of a schema file is not right, then you should expect the error below. Please see, schema documentation for more info. [TODO: This part will be updated once schema doc is finalized ]

      .../build/external-plugins-deps/schemas/PluginName/../AccountsPlugin/Publish.EventStream.AccountList.OutputPayload.schema.json
      *** ERROR: FILE MISSING ***

• Validation script cross-checks that schemas in both producer and consumer plugins are the same and valid. This is just to make sure that sender/publisher and receiver/subscriber agree on the same payload structure. If non-compliant, build process fails:

      .../build/external-plugins-deps/schemas/AccountsDomainPlugin/SubscribeOnStartup.EventStream.AccountsMockPlugin.AccountDetailsLoaded.OutputPayload.schema.json
      .../build/external-plugins-deps/schemas/AccountsDomainPlugin/../AccountsMockPlugin/Publish.EventStream.AccountDetailsLoaded.OutputPayload.schema.json
      *** ERROR: NOT COMPATIBLE ***

• When validation script runs successfully, then you should see:

      .../build/external-plugins-deps/schemas/AccountsJourneyPlugin/../Plugin/Publish.EventStream.CreditAccountModalFormComplete.OutputPayload.schema.json
      *** COMPATIBLE ***