# Entities reference

Copy as Markdown[View as Markdown](/docs/development/guides/resources/entities/reference.md)

***

This page lists the fields, paths, and routes supported by entities.

## Paths[​](#paths "Direct link to Paths")

Entities can be created at the root of your catalog:

```
/entities/{Entity Name}/index.mdx
```

Entities can also be created inside domains, systems, or services:

```
/domains/{Domain Name}/entities/{Entity Name}/index.mdx
/systems/{System Name}/entities/{Entity Name}/index.mdx
/domains/{Domain Name}/systems/{System Name}/entities/{Entity Name}/index.mdx
/services/{Service Name}/entities/{Entity Name}/index.mdx
```

Versioned entities use:

```
/entities/{Entity Name}/versioned/{version}/index.mdx
```

Nested entities use the same `versioned/{version}/index.mdx` pattern inside their entity folder.

## Routes[​](#routes "Direct link to Routes")

| Route                                                    | Description                                    |
| -------------------------------------------------------- | ---------------------------------------------- |
| `/docs/entities/{entity-id}/{version}`                   | Entity documentation page.                     |
| `/visualiser/entities/{entity-id}/{version}`             | Entity resource diagram.                       |
| `/visualiser/domains/{domain-id}/{version}/entity-map`   | Entity map for entities assigned to a domain.  |
| `/visualiser/services/{service-id}/{version}/entity-map` | Entity map for entities assigned to a service. |

## Frontmatter example[​](#frontmatter-example "Direct link to Frontmatter example")

```
---
# Unique identifier for the entity. Used in URLs and resource references.
id: order
# Friendly display name shown in EventCatalog.
name: Order
# Version of this entity documentation.
version: 1.0.0
# Short summary shown in lists, sidebars, and previews.
summary: Represents a customer's purchase.
# The property that uniquely identifies this entity.
identifier: orderId
# Optional. Marks this entity as the aggregate root for the model.
aggregateRoot: true
# Teams or users that own this entity.
owners:
  - ordering-platform
# Properties that describe the shape of the entity.
properties:
  # Unique identifier for this order.
  - name: orderId
    # Data type for the property.
    type: string
    # Whether this property is required.
    required: true
    # Human-readable description of what the property represents.
    description: Unique order identifier.
  # Identifier for the customer that placed the order.
  - name: customerId
    # Data type for the property.
    type: string
    # Whether this property is required.
    required: true
    # Human-readable description of what the property represents.
    description: Customer that placed the order.
    # Entity this property references.
    references: customer
    # Label used to describe the relationship in entity maps.
    relationType: placedBy
    # Identifier property on the referenced entity.
    referencesIdentifier: customerId
  # Current lifecycle state of the order.
  - name: status
    # Data type for the property.
    type: string
    # Allowed values for the property.
    enum:
      - pending
      - confirmed
      - cancelled
---
```

## 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 URLs and resource references.

Example

```
---
id: order
---
```

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

* Type: `string`

Display name of the entity.

Example

```
---
name: Order
---
```

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

* Type: `string`

Version of the entity documentation.

Example

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

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

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

* Type: `string`

Short summary of what the entity represents.

Example

```
---
summary: Represents a customer's purchase.
---
```

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

* Type: `array`

An array of team or user ids that own the entity.

Example

```
---
owners:
  - ordering-platform
---
```

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

* Type: `boolean`

Marks the entity as an aggregate root.

Example

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

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

* Type: `string`

The property that uniquely identifies the entity.

Example

```
---
identifier: orderId
---
```

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

* Type: `array`

Properties that describe the shape of the entity.

Example

```
---
properties:
  - name: orderId
    type: string
    required: true
    description: Unique order identifier.
---
```

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

* Type: `array`

Badges rendered on the entity page.

Example

```
---
badges:
  - content: Aggregate root
    backgroundColor: blue
    textColor: blue
---
```

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

* Type: `object`

Repository metadata for the entity.

Example

```
---
repository:
  language: TypeScript
  url: https://github.com/acme/orders
---
```

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

* Type: `array`

External links or supporting documents attached to the entity.

Example

```
---
attachments:
  - title: Order model runbook
    url: https://runbooks.example.com/orders
    type: runbook
---
```

## Property fields[​](#property-fields "Direct link to Property fields")

| Field                  | Type      | Description                                                                  |
| ---------------------- | --------- | ---------------------------------------------------------------------------- |
| `name`                 | `string`  | Property name.                                                               |
| `type`                 | `string`  | Property type, such as `string`, `UUID`, `datetime`, or another entity name. |
| `required`             | `boolean` | Whether the property is required.                                            |
| `description`          | `string`  | Description of the property.                                                 |
| `references`           | `string`  | Entity id referenced by this property.                                       |
| `referencesIdentifier` | `string`  | Identifier property on the referenced entity.                                |
| `relationType`         | `string`  | Relationship label shown in entity maps.                                     |
| `enum`                 | `array`   | Allowed string values.                                                       |
| `items`                | `object`  | Item type for array properties.                                              |

## EntityPropertiesTable component[​](#entitypropertiestable-component "Direct link to EntityPropertiesTable component")

Use `<EntityPropertiesTable />` in the entity Markdown body to render the entity properties as a table.

```
<EntityPropertiesTable />
```

This is useful when you want the documentation page to show the same properties defined in frontmatter.