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