Domains reference

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

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

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

Domains are Markdown files. They support content, MDX components, and frontmatter.

/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

`id`

Type: string

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

Example
---
id: Orders
---

`name`

Type: string

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

Example
---
name: My orders domain
---

`version`

Type: string

Version of the domain.

Example
---
version: 0.0.1
---

Optional fields

`summary`

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

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

`owners`

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

Example
---
owners:
  - dboyne
  - platform-team
---

`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`

Added in eventcatalog@4.0

An array of system 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`

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`

Added in eventcatalog@3.41.0

An array of agent 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`

Added in eventcatalog@2.36.0

An array of entity 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`

Added in eventcatalog@3.8.0

An array of data product 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`

An array of flow 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`

Added in eventcatalog@3.7.0

An array of message 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`

Added in eventcatalog@3.7.0

An array of message 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`

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

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

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

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`

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 metadata for the domain.

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

`diagrams`

An array of diagrams associated with the domain.

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

`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`

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`

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 library.

Paths​

Routes​

Frontmatter example​

Required fields​

id​

name​

version​

Optional fields​

summary​

owners​

domains​

systems​

services​

agents​

entities​

data-products​

flows​

sends​

receives​

badges​

Use named colors​

Use any CSS color​

Link to external URLs​

specifications​

repository​

diagrams​

visualiser​

editUrl​

attachments​