# Add custom entity types
Every entity you add to your workspace is associated with an entity type. Cortex comes with several built-in entity types, but you can [create unlimited custom entity types](https://docs.cortex.io/ingesting-data-into-cortex/entities/adding-entities/entity-types) to extend your catalogs.
There are two distinct parts of this process: [Creating the entity type itself](#create-custom-entity-types) (via the UI or API), then [creating entities of that custom type](#create-custom-entities) (via the UI, GitOps, or API).
{% hint style="success" %}
Want to learn more? Check out the Cortex Academy course on [Catalogs, Entities, and Relationships](https://academy.cortex.io/courses/understanding-understanding-catalogs-entities-and-relationships), available to all Cortex customers and POVs.
{% endhint %}
## View entity types
To view all entity types, go to **Catalogs > All Entities** then click the [**Entity types** tab](https://app.getcortexapp.com/admin/entities?activeTab=EntityTypes).
A Cortex logo appears next to built-in entity types. When you hover over the logo, you will see a "Powered by Cortex" banner:
The other entity types in the list are custom types.
## Create custom entity types
You can create custom entity types:
* Manually in the Cortex UI
* Via the [API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/entity-types)
When creating an entity type, keep in mind that these will ultimately dictate how you import specific entities later on. After creating the type itself, you will be able to [create entities of that type](#creating-custom-entities) (via the UI, API, or GitOps).
To create, edit, and delete entity types, your user or API key must have the `Edit entity types` permission.
{% tabs %}
{% tab title="Cortex UI" %}
**Create entity types in the Cortex UI**
1. In Cortex, navigate to **Catalogs > All entities**.
2. Click the **Entity types** tab, then click **Create entity type**.\\
3. Configure the form:
* **Name**: Enter a human-readable name that will appear in the catalog for this entity type.
* **Type**: Enter a unique identifier that corresponds to the entity type. This will be used to specify the type defined in the YAML definitions for imported entities.
* **Description**: Optionally, enter a description for the entity type.
* **Display icon**: Select an icon to appear alongside the entity type throughout the app.
* **Schema**: Define a [JSON schema](#json-schema-for-custom-entity-types) that will be used to validate the `x-cortex-validation` block of a given entity’s YAML.
* This can be used to enforce certain attributes about entities, such as a region or version number. Attributes defined in the schema will be required when creating an entity of that type, which can then be validated in Scorecards. Learn more under [JSON schema for custom entity types](#json-schema-for-custom-entity-types).
* In the example screen shot below, we’ve created a custom entity type called `Employee` — this is what we’ll use to represent individuals at our organization. In the schema section, you can see that each profile is required to include an employee’s location. This means every time you create an entity of type "Employee," you will define the employee's location.\\
4. At the bottom of the page, click **Create**.
After saving, the entity type will appear in the **Entity types** tab under **Catalogs > All entities**, and you are now able to import entities of that type.
If you want entities of the new entity type to automatically belong to a specific catalog, you can configure the catalog's defined entity types while [creating a new catalog](#create-catalogs) or you can [edit an existing catalog](#edit-catalogs) to update the entity types.
{% endtab %}
{% tab title="API" %}
**Create entity types via the API**
You can create, update, and delete entity types using the [Cortex API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities).
Learn more about the [JSON schema](#json-schema-for-custom-entity-types) below.
{% endtab %}
{% endtabs %}
### JSON schema for custom entity types
Entity type definitions require a JSON schema that outlines the attributes that entities should conform to.
Custom entity type definitions are powered by the open-source [JSON Schema](https://json-schema.org/) project.
The JSON schema for a custom entity type ensures consistency and validation when creating entities of that type. The attributes listed under `required` in the schema must be defined for entities of that type according to the outlined `properties`.
In the example below, `location` is required when creating this type of entity, but the schema also includes `department` as a possible property.
```json
{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"type": "string"
},
"department": {
"type": "string"
}
}
}
```
| Field | Definition | Required |
| ------------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `type` | Type of entity and/or required component: `array`, `boolean`, `integer`, `null`, `number`, `object`, or `string` | Yes |
| `required` | Required specs for the entity type | |
| `properties` | Properties of the required specs (including `type`) | Yes only if the `required` field is not null |
#### Adding an entity schema for new custom entities
When creating a new entity of the custom type, if the entity type's JSON schema requires certain attributes, you must include the metadata for those attributes on that entity.
Add attributes via JSON schema
While [creating a custom entity in the Cortex UI](#cortex-ui-1), you can enter JSON for the entity's schema into the Schema field.
Based on the [example above](#json-schema-for-custom-entity-types), the entity schema format would look like the following:
```json
{
"location": "San Diego",
"department": "Engineering"
}
```
Add attributes via YAML
If you are following a GitOps workflow, or if you are editing the entity's YAML directly in the Cortex UI, you can update the custom entity's metadata in the YAML.
Based on the [example above](#json-schema-for-custom-entity-types), the entity YAML would look like the following:
```
x-cortex-type: org-employees
x-cortex-definition:
location: San Diego
department: Engineering
```
When creating a custom entity, the `x-cortex-type` (the custom entity type) and the `x-cortex-definition` are required. Learn more under [Create custom entities in the entity descriptor](#entity-descriptor).
#### Metadata in the entity details page
Defining a JSON schema enables visibility on an [entity's detail page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details). The schema and the defined properties will appear under the **Metadata** section on the entity's overview, making it easy for you to identify key specs.
In the example below, the entity "Sally S" displays metadata for the property "location."
## Create custom entities
After [creating your custom entity type](#create-custom-entity-types), you can create entities of that custom type:
* in the Cortex UI
* in the [entity descriptor YAML](https://docs.cortex.io/ingesting-data-into-cortex/entities/..#defining-entities-via-yaml-file) via [GitOps](https://docs.cortex.io/configure/gitops)
* via the [Cortex API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities)
To create custom entities, your user or API key must have the `Edit entities` permission.
{% tabs %}
{% tab title="Cortex UI" %}
**Create custom entities in the Cortex UI**
Before creating a custom entity in the UI, make sure you have UI-based editing enabled for this entity type in [**Settings > GitOps**](https://app.getcortexapp.com/admin/settings/gitops).
1. In the main nav of Cortex, click **Catalogs > All entities**.
2. At the top of the Services page, click **+Import entities**.
3. Choose **Create entities manually**.\
4. Configure the form:
* **Type**: Select your custom entity type.
* **Entity schema**: Enter a JSON schema to define your custom entity.
* For example, if the entity type's schema requires location and department, your new entity's schema might look like this:\\
* Click **Show example** above the schema to view an example of how the entity's schema should be formatted. To use the example as a starting point, click **Copy example** then paste it into the **Entity schema** text editor.
* See [JSON schema for custom entity types](#json-schema-for-custom-entity-types) for more information.
* **Entity name**: Enter a human readable name for your entity.
* **Identifier**: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the `x-cortex-tag`.
* **Description**: Enter a description of the entity to help others understand its purpose.
* **Groups**: Select [groups to segment](https://docs.cortex.io/ingesting-data-into-cortex/entities/groups) your entity.
* **Owners**: Define [ownership](https://docs.cortex.io/ingesting-data-into-cortex/entities/ownership) for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
* **Links**: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
* **Parents**: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the [relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities/relationship-graph).
* **Dependencies**: Select entities that this entity depends on. These can be visualized in the [relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities/relationship-graph).
* **On-call**: Configure on-call information.
* **Repository**: Select the repository associated with this entity.
5. When you are finished, click **Confirm import** at the bottom of the page.
{% endtab %}
{% tab title="Entity descriptor" %}
**Create custom entities in the entity descriptor**
Before creating a custom entity via GitOps, make sure you have UI-based editing disabled for this this entity type in [**Settings > GitOps**](https://app.getcortexapp.com/admin/settings/gitops).
If your entity is of a custom type, you must specify `x-cortex-type` and `x-cortex-definition`.
The `x-cortex-definition` field is validated against the [entity type definition](https://docs.cortex.io/ingesting-data-into-cortex/entities/adding-entities/entity-types) that you created via the UI or API. If your custom entity type does not have specific requirements, entities of that type still need a non-null definition specified, like `x-cortex-definition: {}`.
**Example cortex.yaml**
```yaml
openapi: 3.0.1
info:
title: Sally S
description: Technical writer
x-cortex-tag: employee-sally
x-cortex-type: org-employees
x-cortex-definition:
location: San Diego
department: Engineering
```
{% endtab %}
{% tab title="API" %}
You can create, read, update, and delete entities via the [Cortex API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities).
To delete entities, your API key must have the `Delete entities` permission.
{% endtab %}
{% endtabs %}
## Managing custom entities
### Edit custom entities
It is possible to edit entities after creating them:
1. Navigate to the entity's page.
2. In the upper right corner, click **Configure entity**.
3. Make any desired changes.
* Note: The only field you cannot edit is the identifier.
4. At the bottom of the screen, click **Save changes**.
### Add custom entities to catalogs
After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you [create a custom catalog](#create-catalogs), you can set the entity type criteria.
By default, any [custom entity types](#create-entity-types) you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog's definition.
## Managing custom entity types
After creating a custom entity type, you can view or edit its schema, view a list of entities of that type, and validate the schema of entities of that type.
### View custom entity types
You can view a custom entity type's schema and a list of entities of that type.
1. Navigate to **Catalogs > All entities**, then click the [Entity types tab](https://app.getcortexapp.com/admin/entities?activeTab=types).
2. Click into an entity type.
* The schema is displayed on the entity type page.
* Click the **Entities** tab to view a list of entities of that type.
* Learn more about the health and incident data columns in [Key performance indicators listed for all entities](https://docs.cortex.io/ingesting-data-into-cortex/entities/..#key-performance-indicators-listed-for-all-entities).\\
### Edit custom entity types
1. Navigate to **Catalogs > All entities**, then click the [Entity types tab](https://app.getcortexapp.com/admin/entities?activeTab=types).
2. Click into an entity type.
3. In the upper right corner, click **Edit**.
4. Make changes to your entity type, then at the bottom of the page, click **Save**.
* You cannot edit the entity type's unique identifier.
### Validate an entity schema for a custom entity type
1. Navigate to **Catalogs > All entities**, then click the [Entity types tab](https://app.getcortexapp.com/admin/entities?activeTab=types).
2. Click into an entity type.
3. Click the **Schema linter** tab.
4. In the text editor, paste in your entity's JSON schema to verify that it is properly formatted for this entity type.
* On the right side of the page, click **Show example** to see an example of how the schema should be formatted.
* If you want to use the example as a starting point, click **Copy example**, then paste it into the text editor.
5. In the upper right side of the text editor, click **Validate Schema**.
## Using custom entity types or custom data
In some instances, you may want to use custom data instead of a custom entity type. This is recommended if you need more flexibility for these entity types; they may not always require specific metadata.
While a custom entity type's metadata will appear on the overview of an [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details), custom data does not appear there. Instead, it appears in the **Custom data** sidebar of an entity details page.
It is possible to create an entity type with an empty properties schema:
```json
{
"type": "object",
"required": []
"properties": {}
}
```
This entity type will display in the catalogs, but entities of this type won't be validated against certain specs. Such properties can instead be defined using [custom data](https://docs.cortex.io/ingesting-data-into-cortex/entities/custom-data).
A schema is ideal for enforcing static properties across all entities, while custom data allows users to augment and update attributes.
