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