# Messages reference

Copy as Markdown[View as Markdown](/docs/development/guides/resources/messages/reference.md)

***

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

Messages are modeled as three collections:

* `events`
* `commands`
* `queries`

## Paths[​](#paths "Direct link to Paths")

Messages can be created at the root of their collection:

* events
  <!-- -->
  /
  * {Event Name}
    <!-- -->
    /
    * index.mdx
* commands
  <!-- -->
  /
  * {Command Name}
    <!-- -->
    /
    * index.mdx
* queries
  <!-- -->
  /
  * {Query Name}
    <!-- -->
    /
    * index.mdx

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

* domains

  <!-- -->

  /

  * {Domain Name}

    <!-- -->

    /

    * events
      <!-- -->
      /
      * {Event Name}
        <!-- -->
        /
        * index.mdx
    * systems
      <!-- -->
      /
      * {System Name}
        <!-- -->
        /
        * services
          <!-- -->
          /
          * {Service Name}
            <!-- -->
            /
            * commands
              <!-- -->
              /
              * {Command Name}
                <!-- -->
                /
                * index.mdx

* systems
  <!-- -->
  /
  * {System Name}
    <!-- -->
    /
    * services
      <!-- -->
      /
      * {Service Name}
        <!-- -->
        /
        * events
          <!-- -->
          /
          * {Event Name}
            <!-- -->
            /
            * index.mdx

Versioned messages use:

* events
  <!-- -->
  /
  * {Message Name}
    <!-- -->
    /
    * versioned
      <!-- -->
      /
      * {version}
        <!-- -->
        /
        * index.mdx

## Routes[​](#routes "Direct link to 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[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to id")

* Type: `string`

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

Example

```
---
id: OrderCreated
---
```

### `name`[​](#name "Direct link to name")

* Type: `string`

Display name of the message.

Example

```
---
name: Order Created
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the message documentation.

Example

```
---
version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to summary")

* Type: `string`

Short summary of what the message represents.

Example

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

### `owners`[​](#owners "Direct link to owners")

* Type: `array`

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

Example

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

### `schemaPath`[​](#schemaPath "Direct link to schemaPath")

* Type: `string`

Path to the message schema.

Example

```
---
schemaPath: schema.json
---
```

### `schemas`[​](#schemas "Direct link to schemas")

* Type: `array`

Schema references associated with the message.

Example

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

### `channels`[​](#channels "Direct link to channels")

* Type: `array`

Inline channel references for the message.

Example

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

### `operation`[​](#operation "Direct link to operation")

* Type: `object`

HTTP operation metadata shown on the visualizer node.

Example

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

### `badges`[​](#badges "Direct link to badges")

* Type: `array`

Badges rendered on the message page.

Example

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

### `repository`[​](#repository "Direct link to repository")

* Type: `object`

Repository metadata for the message.

Example

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

### `attachments`[​](#attachments "Direct link to 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[​](#operation-fields "Direct link to 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[​](#schema-examples "Direct link to 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
---
```