# Domains reference

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

***

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

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

Domains can be created at the root of the `domains` folder:

```
/domains/{Domain Name}/index.mdx
```

Subdomains can be created inside a domain:

```
/domains/{Domain Name}/subdomains/{Subdomain Name}/index.mdx
```

## Routes[​](#routes "Direct link to Routes")

| Route                                                       | Description                                     |
| ----------------------------------------------------------- | ----------------------------------------------- |
| `/docs/domains/{domain-id}/{version}`                       | Domain documentation page.                      |
| `/visualiser/domains/{domain-id}/{version}`                 | Domain resource diagram.                        |
| `/visualiser/domains/{domain-id}/{version}/systems-context` | System context map for systems inside a domain. |
| `/visualiser/domains/{domain-id}/{version}/entity-map`      | Entity map for entities inside a domain.        |

## Frontmatter example[​](#frontmatter-example "Direct link to Frontmatter example")

Domains are Markdown files. They support content, MDX components, and [frontmatter](https://jekyllrb.com/docs/front-matter/).

/domains/Orders/index.mdx (example)

```
---
# id of your domain, used for slugs and references in EventCatalog.
id: Orders

# Display name of the domain, rendered in EventCatalog.
name: Orders

# Version of the domain.
version: 0.0.1

# Short summary of your domain.
summary: |
  Domain that contains order related information.

# Optional owners, references teams or users.
owners:
  - dboyne

# Optional systems. Groups systems into this domain.
systems:
  # System id to include in this domain.
  - id: PaymentProcessingSystem
    # Optional version of the system. Latest version is used if not provided.
    version: 1.0.0

# Optional services. Groups services into this domain.
services:
  # Service id to include in this domain.
  - id: PaymentService
    # Optional version of the service. Latest version is used if not provided.
    version: 0.0.1

# Optional flows associated with this domain.
flows:
  # Flow id to include in this domain.
  - id: OrderProcessing
    # Optional version of the flow. Latest version is used if not provided.
    version: 1.0.0

# Optional messages this domain sends.
sends:
  # Message id sent by this domain.
  - id: OrderCreated
    # Optional version of the message. Latest version is used if not provided.
    version: 1.0.0

# Optional messages this domain receives.
receives:
  # Message id received by this domain.
  - id: PaymentInitiated
    # Optional version of the message. Latest version is used if not provided.
    version: 1.0.0

# Optional badges, rendered to UI by EventCatalog.
badges:
  # Badge text.
  - content: New domain
    # Badge background color.
    backgroundColor: blue
    # Badge text color.
    textColor: blue
    # Optional icon from the supported icon set.
    icon: BoltIcon
---

## Overview

Domain that contains all services related to orders.

<NodeGraph />
```

## Required fields[​](#required-fields "Direct link to Required fields")

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

* Type: `string`

Unique id of the domain. EventCatalog uses this for references and slugs.

Example

```
---
id: Orders
---
```

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

* Type: `string`

Name of the domain. This is used to display the domain name in the UI.

Example

```
---
name: My orders domain
---
```

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

* Type: `string`

Version of the domain.

Example

```
---
version: 0.0.1
---
```

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

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

Short summary of your domain, shown on domain summary pages.

Example

```
---
summary: |
  Domain that contains everything about orders.
---
```

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

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

Example

```
---
owners:
  - dboyne
  - platform-team
---
```

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

An array of subdomain ids that belong to this domain.

Example

```
---
domains:
  - id: Payments
  - id: Shipping
    # Optional version of the subdomain, latest version is used if not provided.
    version: 1.0.0
---
```

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

**Added in** `eventcatalog@4.0`

An array of [system](/docs/development/guides/systems/introduction.md) ids that belong to this domain.

Example

```
---
systems:
  - id: CheckoutSystem
  - id: PaymentProcessingSystem
    # Optional version of the system, latest version is used if not provided.
    version: 1.0.0
---
```

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

An array of service ids that belong to this domain.

Example

```
---
services:
  - id: InventoryService
  - id: OrderService
    # Optional version of the service, latest version is used if not provided.
    version: 0.0.1
---
```

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

**Added in** `eventcatalog@3.41.0`

An array of [agent](/docs/development/guides/resources/agents/introduction.md) ids that belong to this domain.

Example

```
---
agents:
  - id: FraudReviewAgent
  - id: CustomerSupportAgent
    # Optional version of the agent, latest version is used if not provided.
    version: 1.0.0
---
```

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

**Added in** `eventcatalog@2.36.0`

An array of [entity](/docs/development/guides/resources/entities/introduction.md) ids that belong to this domain.

Example

```
---
entities:
  - id: Order
  - id: OrderItem
    # Optional version of the entity, latest version is used if not provided.
    version: 0.0.1
---
```

### `data-products`[​](#data-products "Direct link to data-products")

**Added in** `eventcatalog@3.8.0`

An array of [data product](/docs/development/guides/resources/data-products/introduction.md) ids that belong to this domain.

Example

```
---
data-products:
  - id: order-analytics
  - id: payment-analytics
    # Optional version of the data product, latest version is used if not provided.
    version: 1.0.0
---
```

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

An array of [flow](/docs/development/guides/resources/flows/introduction.md) ids that are associated with this domain.

Example

```
---
flows:
  - id: OrderProcessing
  - id: PaymentFlow
    # Optional version of the flow, latest version is used if not provided.
    version: 1.0.0
---
```

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

**Added in** `eventcatalog@3.7.0`

An array of [message](/docs/development/guides/resources/messages/what-are-messages.md) ids that this domain sends or publishes.

In Domain-Driven Design these can be classed as domain events, which are events that are published by the domain.

This allows you to document messages at a domain level and have services document them as the implementation of the domain event.

Where to store these messages?

You can store messages anywhere in your catalog. If you prefer, you can store them in your domain folder.

```
domains/
  Orders/
    events/
      OrderCreated/
        index.mdx
```

Example

```
---
sends:
  - id: OrderCreated
  - id: PaymentProcessed
    # Optional version of the message, latest version is used if not provided.
    version: 1.0.0
---
```

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

**Added in** `eventcatalog@3.7.0`

An array of [message](/docs/development/guides/resources/messages/what-are-messages.md) ids that this domain receives.

These are typically messages that are consumed by your domain from outside its boundary.

Example

```
---
receives:
  - id: PaymentInitiated
  - id: FraudDetected
    # Optional version of the message, latest version is used if not provided.
    version: 0.0.1
---
```

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

**Added in** `eventcatalog@3.39.4`

An array of badges that get rendered on the page.

Example

```
---
badges:
  - content: My badge
    backgroundColor: green
    textColor: green
    # Optional icon to display from lucide icons.
    # Or the name of a broker, for example Kafka or EventBridge.
    icon: BoltIcon
---
```

#### Use named colors[​](#use-named-colors "Direct link to Use named colors")

Set `backgroundColor` or `textColor` to a named palette token for automatic light and dark mode adaptation.

Supported names: `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`.

Named color example

```
---
badges:
  - content: Critical
    backgroundColor: red
    textColor: red
---
```

#### Use any CSS color[​](#use-any-css-color "Direct link to Use any CSS color")

You can also pass any valid CSS color value directly: hex (`#ff0000`), `rgb()`, `hsl()`, `oklch()`, or a CSS variable (`var(--my-color)`).

CSS color example

```
---
badges:
  - content: Custom
    backgroundColor: "#6366f1"
    textColor: "#ffffff"
---
```

#### Link to external URLs[​](#link-to-external-urls "Direct link to Link to external URLs")

**Added in** `eventcatalog@3.39.6`

Add a `url` to a badge to make it render as a clickable link with an external-link icon. When `url` is omitted, the badge renders as a plain label.

Link badge example

```
---
badges:
  - content: View Runbook
    url: https://runbooks.example.com/my-domain
    backgroundColor: blue
    textColor: white
---
```

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

**Added in** `eventcatalog@2.6.0`

Specifications to include on the domain page.

**Added in** `eventcatalog@2.39.1`

You can assign one or more specifications to a domain.

Example

```
---
specifications:
  - type: asyncapi
    path: order-service-asyncapi.yaml
    name: AsyncAPI Specification
  - type: openapi
    path: openapi.yml
    name: OpenAPI Specification
  - type: graphql
    path: graphql.yml
    name: GraphQL Specification
---
```

| Property | Type     | Required | Description                                                      |
| -------- | -------- | -------- | ---------------------------------------------------------------- |
| `type`   | `string` | Yes      | The type of specification.                                       |
| `path`   | `string` | Yes      | The path to the specification file.                              |
| `name`   | `string` | No       | Optional friendly name of the specification, rendered in the UI. |

**Older versions of EventCatalog (< 2.39.0)**

If you are using an older version of EventCatalog, use the following syntax.

Example

```
---
specifications:
  asyncapiPath: order-service-asyncapi.yaml
  openapiPath: openapi.yml
---
```

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

Repository metadata for the domain.

Example

```
---
repository:
  url: https://github.com/event-catalog/eventcatalog
  language: TypeScript
---
```

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

An array of diagrams associated with the domain.

Example

```
---
diagrams:
  - id: orders-context
    version: 1.0.0
---
```

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

**Added in** `eventcatalog@2.39.2`

Turn off the visualiser for this resource. This means the resource will not be included in the visualiser or the navigation bar for the visualiser.

Default: `true`

Example

```
---
visualiser: false
---
```

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

**Added in** `eventcatalog@2.49.4`

Override the default edit URL for the page. This is used to navigate the user to the edit page for the page, for example GitHub or GitLab.

Example

```
---
editUrl: https://github.com/event-catalog/eventcatalog/edit/main/domains/Orders/index.mdx
---
```

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

**Added in** `eventcatalog@2.57.2`

An array of attachments for this domain.

Example

```
---
attachments:
  - url: https://example.com/adr/001
    title: ADR-001 - Use Kafka for asynchronous messaging
    description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
    type: architecture-decisions
    icon: FileTextIcon
  - https://example.com/adr/002
---
```

The attachments can be a URL string or an object with additional properties.

| Property      | Type     | Required | Description                                                                                          |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `url`         | `string` | Yes      | The URL of the attachment.                                                                           |
| `title`       | `string` | No       | The title of the attachment.                                                                         |
| `description` | `string` | No       | The description of the attachment.                                                                   |
| `type`        | `string` | No       | The type of the attachment, used to group attachments in the UI.                                     |
| `icon`        | `string` | No       | The icon of the attachment. You can pick from the [lucide icons](https://lucide.dev/icons/) library. |