---
title: Defining Custom Entities | Shopware Community Hub
description: >-
  Learn how to define Custom Entities in an App with the entities.xml file and
  extend the Shopware database without writing any PHP code.
canonical_url: 'https://hub.shopware.com/learn/unit/app-defining-custom-entities'
---

# Defining Custom Entities

<LearningObjectives>

- **Define** a **Custom Entity** in an App using the **`entities.xml`** file.
- Run an **App Update** to apply entity definitions to the database.
- **Verify** that a new database table was created for the Custom Entity.
- **Troubleshoot errors** related to the `entities.xml` file.

</LearningObjectives>

# Defining Custom Entities

Now that you understand what Custom Entities are and when to use them, it's time to create your first one!

In this learning unit, you will learn how to **define a Custom Entity** using the `entities.xml` file and see how Shopware automatically creates the necessary database tables.

## Code-Along

To follow along, use the following command within the ShopwareStoreTracker directory (`[shopRoot]/custom/apps/ShopwareStoreTracker`):

```bash
git checkout tags/custom_entities--start
```

## How to Create a Custom Entity With an App

Every App can define its own Custom Entities in the `entities.xml` file. You can find (or create) this file under the `[app_root]/Resources` directory --> `[app_root]/Resources/entities.xml`. Unlike plugins, no PHP code or migration files are required. Shopware reads this file directly and manages the database schema automatically.

As mentioned in the Course Introduction, our 'Store Tracker' App should collect and display information about Physical Stores owned by a business. To allow us to import data about each Physical Store, let's create an `entities.xml` file with the following definition:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
        <entity name="ce_physical_shop">
            <fields>
                <string name="name" store-api-aware="true" translatable="false" />
                <json name="street_address" store-api-aware="true" translatable="false" />
                <string name="country" store-api-aware="true" translatable="false" />
                <text name="description" store-api-aware="true" translatable="true" />
                <bool name="open_to_public" default="true" store-api-aware="true" />
                <email name="email" required="true" store-api-aware="true" />
            </fields>
        </entity>
</entities>
```

Create the file at `[shopRoot]/custom/apps/ShopwareStoreTracker/Resources/entities.xml` and paste the contents inside it. After saving the `entities.xml` file, update your App so that Shopware applies the new entity definition.

<Callout title="A Refresher on Updating Apps" type="info">

Increase the version number of your App's `manifest.xml` file and run the following command from your Shopware root directory:

```bash
bin/console app:update
```

Feel free to revisit the first [course](/learn/unit/the-manifest-file#versioningyourapp) if you need a refresher on how to update Apps.

</Callout>

During the execution of the `app:update` command, Shopware will detect the creation of a new Entity definition inside the `entities.xml` file, performing all necessary database operations (in this case, creating a new Table named `ce_physical_shop`).
If you later add or remove fields or entities, Shopware will automatically adjust the database schema for you, no PHP migrations required.

## Troubleshooting: 'No DTD Found'

### Issue

When running the `app:update` command, you may encounter an error like:

> `ShopwareStoreTracker Unable to parse file "/home/scotta/Projects/shopware/custom/apps/ShopwareStoreTracker/Resources/entities.xml". Message: [ERROR 522] Validation failed: no DTD found ! (in n/a - line 2, column 202)`

### Possible Resolution

This usually happens because of a **syntax error** in the `entities.xml` file, for example, missing brackets, invalid nesting or typos in attribute names. To find and fix these issues quickly, use a modern IDE (e.g., [VSCode](https://code.visualstudio.com/), [PhpStorm](https://www.jetbrains.com/phpstorm/)) or an XML linter. Both of these tools can provide validation and highlighting against the schema. Make sure your XML matches the [Shopware entity schema](https://github.com/shopware/shopware/blob/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd).

## Checking for the new Table in the Database

After a successful update for our Application, a new table called `ce_physical_shop` should have been created in our Shopware Database (all Custom Entities from a Shopware App have to be prefixed with `ce_`).

To validate that our new table exists within the database, log in to Adminer (either using your devenv integration at `localhost:9080` or using the [FROSH Admin Extension](https://store.shopware.com/en/frosh79014577529f/adminer-for-admin.html?srsltid=AfmBOopHlVinOxAjty9uj5s7lQQxAx47fJH66e7roKGmd9Ijj-8OTHRs)), and open the list of tables and look for `ce_physical_shop`. You should see the newly created table somewhere within the search results:

![Adminer tables](assets/ce-physical-shop.png)

## Code-Along (end)

To see what the final result of this learning unit should look like, run the following command:

```bash
git checkout tags/custom_entities--end
```

<Callout title="Removing Working Changes" type="warning">

If you have local changes, you will need to run `git reset --hard HEAD` in the App directory. Be mindful that this command will destroy any local changes!

</Callout>

## Summary

With the declarative syntax of the `entities.xml` file, you don't need to write PHP migrations to update the database schema. Shopware automatically creates and updates the necessary tables for you.

This approach is:

- **Simpler**: You edit XML instead of writing PHP code for the migrations.
- **More reliable**: Shopware ensures schema changes are applied correctly.
- **Faster**: No extra migration files are needed, which speeds up the development process.

Very well! You have extended Shopware's data model with your own entity.

In the next learning unit, you will use the **Shopware Admin API** to **send a POST request** that creates data in your new Custom Entity.