# Add entities to resources

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

***

Adding [entities](/docs/development/guides/resources/entities/introduction.md) to resources helps people understand which business concepts a domain, system, or service owns, uses, or documents.

In EventCatalog, entities can be connected to:

* [Domains](/docs/development/guides/domains/introduction.md)
* [Systems](/docs/development/guides/systems/introduction.md)
* [Services](/docs/development/guides/resources/services/introduction.md)

## Add entities using frontmatter[​](#add-entities-using-frontmatter "Direct link to Add entities using frontmatter")

Add entities to a resource using the `entities` array in the resource frontmatter.

/domains/Ordering/index.mdx

```
---
id: ordering
name: Ordering
version: 1.0.0
# define entities that belong to this domain
entities:
  - id: order
    version: 1.0.0
  - id: customer
---
```

You can use the same pattern for systems:

/domains/Ordering/systems/order-management/index.mdx

```
---
id: order-management
name: Order Management
version: 1.0.0
# define entities that are part of this system
entities:
  - id: order
  - id: shipment
---
```

And services:

/services/OrderService/index.mdx

```
---
id: order-service
name: Order Service
version: 1.0.0
# define entities this service owns, reads, writes, or exposes
entities:
  - id: order
  - id: customer
---
```

The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced entity.

## Keep entities inside the resource folder[​](#keep-entities-inside-the-resource-folder "Direct link to Keep entities inside the resource folder")

You can also define entities inside a resource folder to keep related business model documentation together.

* domains

  <!-- -->

  /

  * Ordering

    <!-- -->

    /

    * index.mdx

    * entities

      <!-- -->

      /

      * Order
        <!-- -->
        /
        * index.mdx
      * Customer
        <!-- -->
        /
        * index.mdx

This structure makes the domain the entry point for the entities that belong to that business boundary.

Entities can also live inside services:

* services

  <!-- -->

  /

  * OrderService

    <!-- -->

    /

    * index.mdx
    * entities
      <!-- -->
      /
      * Order
        <!-- -->
        /
        * index.mdx

This structure is useful when the entity is owned by, exposed by, or tightly coupled to one service.

## Keep shared entities at the root[​](#keep-shared-entities-at-the-root "Direct link to Keep shared entities at the root")

Entities can live at the root of the catalog when they are shared across multiple domains, systems, or services.

* entities

  <!-- -->

  /

  * Customer
    <!-- -->
    /
    * index.mdx
  * Payment
    <!-- -->
    /
    * index.mdx

Use frontmatter when the entity is shared across multiple resources. Keep the entity inside a resource folder when the entity is owned by that resource and should move with it.

## Show entities on resource pages[​](#show-entities-on-resource-pages "Direct link to Show entities on resource pages")

When a domain, service, or system references entities, EventCatalog shows that relationship on the resource page.

Domains and services can also show entity maps, which help people understand the entity relationships inside that part of your architecture.

Learn more in [entity maps](/docs/development/guides/resources/entities/entity-maps.md) and [model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships.md).

For the complete list of supported fields, see the [entities reference](/docs/development/guides/resources/entities/reference.md).