Domain event documentation

gistfile1.txt

Scenario: different business teams building parts of a product, splitted by business domains. We are anly communicate via domain events published to a message bus and sometimes via published links.
As the domain events are the "contracts" between the business domains we want to declare and enforce the schemas of the events. 
Our solution is built in node but the concept could work in any stack.

Components:

• One npm package (called domain-events ;) ) with the domain event schemas as JSON (http://json-schema.org/draft-04/schema) and with example. These examples will be displayed in the documentation.
• One documentation service based on https://github.com/cloudflare/doca
  • references the domain events as dependency
  • have one build step "build": "doca init -i node_modules/domain-events/json-schema"

This solve the problem of the documentation but we want to enforce that only events published as domain-event are allowed on the message bus. On the other hand all we have shared packages to produce respectively consumer events from our bus. After this it was the easy and logical step to include the domain-event package in the consumer/producer packages and use it there in the validation step. Additionally in order to be backward compatible we allow unknown properties in the consumer validation but not in the producer validation.

Regarding the (current) process:

• the domain-events can be changed via pull requests and reviewed and accepted by minimum 2 people from belonging to the group of architecture owner group (similar to a guild)
• the payload can be defined by the producing business team (having some conventions of course) but the envelope is fixed:

 {
  "id": "event.json",
  "title": "Event",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Schema for the domain event envelope that is used by every event.",
  "type": "object",
  "properties": {
    "eventId": {
      "type": "string",
      "description": "An Id which is unique for the entityId. Shall be a v1-uuid (time-based).",
      "example": "4a4c0290-354f-11e7-a919-92ebcb67fe33"
    },
    "eventType": {
      "type": "string",
      "enum": [
        "offer.accepted"
      ],
      "example": "offer.accepted"
    },
    "entityId": {
      "type": "string",
      "description": "An Id which is unique among all the entities of the same entityType. Shall be a v1-uuid (time-based).",
      "example": "4a4c0290-354f-11e7-a919-92ebcb67fe33"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 DateTimeStamp in UTC with millisecond precision.",
      "example": "2017-01-01T12:00:00.123Z"
    },
    "version": {
      "type": "integer",
      "example": 1
    },
    "correlationId": {
      "type": "string",
      "description": "A unique ID used to track the flow of data, commands, events and alike through the whole domain.",
      "example": "4a4c0290-354f-11e7-a919-92ebcb67fe33"
    },
    "payload": {
      "type": "object",
      "description": "Must contain the entityId plus other fields that have changed in the entity. 'Flat' payloads shall be preferred....",
      "properties": {
        "id": {...
        },
        ...
      },
      "required": [
      ...
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "eventId",
    "eventType",
    "entityId",
    "createdAt",
    "version",
    "payload",
    "correlationId"
  ],
  "additionalProperties": false
}

Wow! There is a lot of complexity in this workflow proposal. The schema looks pretty common. Maybe you are doing something too unclear / much things with this kind of "messaging"?