# Entity frontmatter API

Copy as Markdown[View as Markdown](/docs/api/entity-api.md)

***

## Overview[​](#overview "Direct link to Overview")

Entities are just markdown files, with this comes the use of Content, MDX components and also [front-matter](https://jekyllrb.com/docs/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[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to id")

* Type: `string`

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

Example

```
---
  id: User
---
```

### `name`[​](#name "Direct link to name")

* Type: `string`

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

Example

```
---
  name: User
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the entity.

Example

```
---
  version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to 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`[​](#aggregateroot "Direct link to aggregateroot")

* Type: `boolean`

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

Example

```
---
  aggregateRoot: true
---
```

### `identifier`[​](#identifier "Direct link to identifier")

* Type: `string`

The unique identifier property for this entity.

Example

```
---
  identifier: userId
---
```

### `properties`[​](#properties "Direct link to 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`[​](#badges "Direct link to badges")

**Added in** `eventcatalog@3.39.4`

An array of badges that get rendered on the page.

Example

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

#### Use named colors[​](#use-named-colors "Direct link to Use named colors")

Set `backgroundColor` or `textColor` to a named palette token for automatic light/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[​](#use-any-css-color "Direct link to 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[​](#link-to-external-urls "Direct link to 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-entity
      backgroundColor: blue
      textColor: white
---
```

### `editUrl`[​](#editUrl "Direct link to 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`[​](#detailsPanel "Direct link to 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](/assets/images/domain-details-panel-71f92ae7e5cc2ed29bb9254c2bd3dcb4.png)

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`[​](#attachments "Direct link to 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](https://lucide.dev/icons/) library. |