Event Definition

Event definition is used to establish the schema of the payload/data. We use JSON Schema for this purpose as it's flexible for simple to hierarchical structures and arrays.

Event definitions should be managed the same way products manage their database schemas, for instance. Scripts to manage them should be built into the CI/CD pipelines. See: Create Event Definitions

Naming convention:

Use {entity}-{action}-v{version} style for naming event definitions for publishing. For example, salesorder-created-v1, salesorder-invoiced-v1

Use schema-only-{entity}-{action}-v{version} for naming event definitions used for schema mapping as consumer product. For example, schema-only-salesorder-created-v1

Samples:

Here are a few sample schemas and validators that can be specified to describe the fields.

Basic:

{
    "properties": {
        "name": {
            "type": "string"
        },
        "orderNumber": {
            "type": "integer"
        },
        "active": {
            "type": "boolean"
        },
        "region": "string"
    }
}

With constraints:

{
    "properties": {
        "name": {
            "type": "string",
            "maxLength": 24
        },
        "orderNumber": {
            "type": "number",
            "minimum": 1000,
            "maximum": 9999
        },
        "active": {
            "type": "boolean"
        },
        "region": {
            "enum": [
                "east",
                "west",
                "north",
                "south"
            ]
        }
    },
    "required": [
        "name",
        "orderNumber"
    ]
}

Arrays (some tools define arrays with [] which should be avoided to be compatible with Data Mapper):

{
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 24
    },
    "orderNumber": {
      "type": "number",
      "minimum": 1000,
      "maximum": 9999
    },
    "active": {
      "type": "boolean"
    },
    "region": {
      "enum": [
        "east",
        "west",
        "north",
        "south"
      ]
    },
    "lineItems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "partId": {
            "type": "string"
          },
          "qty": {
            "type": "integer"
          }
        }
      }
    }
  },
  "required": [
    "name",
    "orderNumber"
  ]
}

Using XML Schema for payload:

XML schema has to be embedded within the outer JSON schema and the property named as "xmlContent"

{
  "xmlContent": "<xs:schema attributeFormDefault=\"unqualified\" elementFormDefault=\"qualified\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\"><xs:element name=\"sample\"> <xs:complexType><xs:sequence><xs:element type=\"xs:string\" name=\"name\"/><xs:element type=\"xs:int\" name=\"orderNumber\"/><xs:element type=\"xs:string\" name=\"active\"/> </xs:sequence></xs:complexType></xs:element></xs:schema>"
}