Entity frontmatter API

Overview

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

Here is an example of of a basic entity.

/entities/User/index.mdx (example)

---
# id of the entity
id: "User"

# Display name of the entity, rendered in EventCatalog
name: "User"

# version for your entity 
version: "1.0.0"

# Short summary of your entity
summary: "Represents a user in the system"

# Whether this entity is an aggregate root
aggregateRoot: true

# The unique identifier for this entity
identifier: "userId"

# Properties of the entity
properties:
  - name: "userId"
    type: "string"
    required: true
    description: "Unique identifier for the user"
  - name: "email"
    type: "string"
    required: true
    description: "User's email address"
  - name: "firstName"
    type: "string"
    required: true
    description: "User's first name"
  - name: "lastName"
    type: "string"
    required: true
    description: "User's last name"
  - name: "dateOfBirth"
    type: "date"
    required: false
    description: "User's date of birth"
  - name: "profileId"
    type: "string"
    required: false
    description: "Reference to user's profile"
    references: "Profile"
    referencesIdentifier: "profileId"
    relationType: "one-to-one"

# Badges to display
badges:
  - content: "Core Entity"
    backgroundColor: "blue"
    textColor: "white"
---

The User entity represents a user in our system and serves as an aggregate root for user-related operations.

This entity contains core user information and is referenced by multiple services across the platform.

<!-- Add any markdown you want, the entity will render in its own page /docs/entities/{Entity}/{version} -->

Required fields

id

• Type: string

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

Example

---
  id: User
---

name

• Type: string

Name of the entity this is used to display the name on the UI.

Example

---
  name: User
---

version

• Type: string

Version of the entity.

Example

---
  version: 1.0.0
---

Optional fields

summary

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

Example

---
  summary: |
    Represents a user in the system with personal information and authentication details
---

aggregateRoot

• Type: boolean

Indicates whether this entity is an aggregate root in Domain-Driven Design terms.

Example

---
  aggregateRoot: true
---

identifier

• Type: string

The unique identifier property for this entity.

Example

---
  identifier: userId
---

properties

• Type: Property[]

List of properties that define the structure of the entity.

Example

---
properties:
  - name: "userId"
    type: "string"
    required: true
    description: "Unique identifier for the user"
  - name: "email"
    type: "string"
    required: true
    description: "User's email address"
  - name: "profileId"
    type: "string"
    required: false
    description: "Reference to user's profile"
    references: "Profile"
    referencesIdentifier: "profileId"
    relationType: "one-to-one"
---

Each property can have the following fields:

• name (required): The name of the property
• type (required): The data type of the property
• required (optional): Whether the property is required
• description (optional): Description of the property
• references (optional): References another entity
• referencesIdentifier (optional): The identifier used for the reference
• relationType (optional): Type of relationship (e.g., "one-to-one", "one-to-many")

badges

An array of badges that get rendered on the page.

Example

---
  badges:
    - content: Core Entity
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      icon: BoltIcon
---

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/entities/User/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.

Example

---
  detailsPanel:
    domains:
      visible: false
    services:
      visible: false
    messages:
      visible: false
    versions:
      visible: false
    owners:
      visible: false
---

Options:

Property	Type	Required	Description
domains	object	No	An object with a visible property to show/hide the domains section
services	object	No	An object with a visible property to show/hide the services section
messages	object	No	An object with a visible property to show/hide the messages section
versions	object	No	An object with a visible property to show/hide the versions section
changelog	object	No	An object with a visible property to show/hide the changelog button
owners	object	No	An object with a visible property to show/hide the owners section

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:

Property	Type	Required	Description
url	string	Yes	The url of the attachment
title	string	optional	The title of the attachment
description	string	optional	The description of the attachment
type	string	optional	The type of the attachment, this will be used to group attachments together in the UI
icon	string	optional	The icon of the attachment, you can pick from the lucide icons library.