Messages reference

View as Markdown

---

This page lists the fields, paths, and routes supported by messages.

Messages are modeled as three collections:

• events
• commands
• queries

Paths

Messages can be created at the root of their collection:

Messages can also be created inside domains, systems, and services:

Versioned messages use:

Routes

Route	Description
/docs/events/{event-id}/{version}	Event documentation page.
/docs/commands/{command-id}/{version}	Command documentation page.
/docs/queries/{query-id}/{version}	Query documentation page.
/visualiser/events/{event-id}/{version}	Event resource diagram.
/visualiser/commands/{command-id}/{version}	Command resource diagram.
/visualiser/queries/{query-id}/{version}	Query resource diagram.

Required fields

id

• Type: string

Unique id of the message. EventCatalog uses this for URLs and resource references.

Example

---
id: OrderCreated
---

name

• Type: string

Display name of the message.

Example

---
name: Order Created
---

version

• Type: string

Version of the message documentation.

Example

---
version: 1.0.0
---

Optional fields

summary

• Type: string

Short summary of what the message represents.

Example

---
summary: Published when an order has been accepted.
---

owners

• Type: array

An array of team or user ids that own the message.

Example

---
owners:
  - ordering-platform
---

schemaPath

• Type: string

Path to the message schema.

Example

---
schemaPath: schema.json
---

schemas

• Type: array

Schema references associated with the message.

Example

---
schemas:
  - path: schema.json
    name: JSON schema
    format: jsonschema
---

channels

• Type: array

Inline channel references for the message.

Example

---
channels:
  - id: orders-topic
    address: orders.events
    protocol: kafka
---

operation

• Type: object

HTTP operation metadata shown on the visualizer node.

Example

---
operation:
  method: POST
  path: /orders
  statusCodes:
    - "201"
    - "400"
---

badges

• Type: array

Badges rendered on the message page.

Example

---
badges:
  - content: Public event
    backgroundColor: green
    textColor: green
---

repository

• Type: object

Repository metadata for the message.

Example

---
repository:
  language: TypeScript
  url: https://github.com/acme/orders
---

attachments

• Type: array

External links or supporting documents attached to the message.

Example

---
attachments:
  - title: Event contract review
    url: https://docs.example.com/order-created-review
    type: document
---

Operation fields

Use operation to document HTTP metadata for an event, command, or query.

---
operation:
  method: POST
  path: /orders
  statusCodes:
    - "201"
    - "400"
---

Field	Type	Description
method	GET, POST, PUT, DELETE, PATCH	HTTP method for the operation.
path	string	API path for the operation.
statusCodes	array	HTTP status codes the operation may return.

Schema examples

Use schemaPath to attach a schema to the message.

---
schemaPath: schema.json
---

You can also use schema references when a message has multiple schemas or named schemas.

---
schemas:
  - path: schema.json
    name: JSON schema
    format: jsonschema
---