Skip to main content

Domain frontmatter API

Overview​

Domains are just markdown files, with this comes the use of Content, MDX components and also front-matter.

Here is an example of the domain frontmatter you will find in your domain files.

/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 services. Groups services into this domain.
services:
    - id: PaymentService
      version: 0.0.1

# Optional flows associated with this domain
flows:
    - id: OrderProcessing
      version: 1.0.0

# Optional messages this domain sends _(added in 3.7.0)_
sends:
    - id: OrderCreated
      version: 1.0.0

# Optional messages this domain receives _(added in 3.7.0)_
receives:
    - id: PaymentInitiated
      version: 1.0.0

# Optional badges, rendered to UI by EventCatalog
badges:
    - content: New domain
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---

## Overview

Domain that contains all services that are related to the orders domain within FakeCompany.

<NodeGraph />

Required fields​

id​

  • Type: string

Unqiue 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 name on 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 user ids that own the domain.

Example
---
  owners:
    - dboyne
    - mSmith
---

services​

An array of services ids that belong to the this domain. Which services belong to this domains bounded context.

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

entities​

Added in eventcatalog@2.36.0

An array of entities ids that belong to the this domain. Which entities belong to this domains bounded context.

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

flows​

An array of flows 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 messages ids that this domain sends/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 messags (e.g events) 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. But remember you can also reference them in your services anyway.

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 messages ids that this domain receives.

These typically are messages that are consumed by your domain (external messages).

You can store these anywhere in your catalog, and your domain can just reference them.

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

badges​

An array of badges that get rendered on the page.

Example
---
  badges:
    - content: My badge
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---

specifications​

Added in eventcatalog@2.6.0

Specifications to include on the 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
---
PropertyTypeRequiredDescription
typestringYesThe type of specification, currently only asyncapi and openapi are supported
pathstringYesThe path to the specification file
namestringNoOptional 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 you will need to use the following syntax.

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

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 (e.g GitHub, GitLab url).

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

detailsPanel​

Added in eventcatalog@2.53.0

Override the default details panel for the page. You can use this show/hide areas of the details panel.

Details panel

Example
---
  detailsPanel:
    services:
      visible: false
    entities:
      visible: true
    messages:
      visible: false
    ubiquitousLanguage:
      visible: false
---

Options:

PropertyTypeRequiredDescription
servicesobjectNoAn object with a visible property to show/hide the services section
entitiesobjectNoAn object with a visible property to show/hide the entities section
messagesobjectNoAn object with a visible property to show/hide the messages section (sends and receives)
ubiquitousLanguageobjectNoAn object with a visible property to show/hide the ubiquitous language section
repositoryobjectNoAn object with a visible property to show/hide the repository section (e.g GitHub, GitLab url)
versionsobjectNoAn object with a visible property to show/hide the versions section
ownersobjectNoAn object with a visible property to show/hide the owners section
changelogobjectNoAn object with a visible property to show/hide the changelog button

attachments​

Added in eventcatalog@2.57.2

An array of attachments for this resource type.

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

Options:

The attachments can be a url (string) or an object with additional properties.

Object properties:

PropertyTypeRequiredDescription
urlstringYesThe url of the attachment
titlestringoptionalThe title of the attachment
descriptionstringoptionalThe description of the attachment
typestringoptionalThe type of the attachment, this will be used to group attachments together in the UI
iconstringoptionalThe icon of the attachment, you can pick from the lucide icons library.