> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types.md). # Adding custom entity types Cortex ships with built-in entity types—services, domains, and teams—to cover common engineering assets, but an organization's catalog rarely stops there. Custom entity types let you model anything your teams track, such as employees, vendors, data pipelines, and compliance controls, with structured metadata you define and enforce. ## Prerequisites Creating a custom entity type is a two-step process: 1. First, define the ***entity type*** itself (its name, icon, and JSON schema) * Users or API keys must have the `Edit Entity Types` permission 2. Next, [create individual entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/creating-custom-entities.md) of that type via the UI, GitOps, or API. * Users or API keys must have the `Edit Entities` permission ## Creating a custom entity type Users or API keys with the `Edit Entity Types` permission can create, edit, and delete entity types. Custom entity types can be created manually in the Cortex UI or via the API. The type you define— its schema, required fields, and metadata—shape how entities of that type are imported and validated going forward. Once the type exists, you can create entities of that type through the UI, API, or GitOps. When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children. ### Creating a custom entity type manually in the Cortex UI 1. From the main sidebar, expand **All Catalogs**, then select **All entities**. 2. Select the **Entity types** tab. 3. In the upper-right corner, click **Create**, then select **Create new entity type**.\ The **Create entity type** page opens. 4. In the **Details** section, do the following: 1. Under **Entity type name**, enter a human-readable name that will appear in the catalog for this entity type (required). 2. Under **Identifier**, enter a unique identifier consisting of letters, digits, and hyphens that corresponds to the entity type (required). This is used to specify the type defined in the YAML definitions for imported entities. 3. Under **Description**, enter a description for the entity type. 4. Under **Display icon**, click **Edit** to select an icon to appear alongside the entity type throughout Cortex. 5. In the **Schema** section, do the following: 1. Define a [JSON schema](#json-schema-for-custom-entity-types) to 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. * In the example screenshot below, the custom entity type `Employee` represents individuals in an organization. The schema requires each entity to include a `location` , so every entity of type "Employee" must define the employee's location.

A custom entity called "Employee" contains example JSON, demonstrating how to configure a required "location" field.

6. Click **Create**.\ The new entity type now appears in the **Entity types** tab. You can now import entities of the same type into Cortex. To automatically assign entities of this type to a specific catalog, configure the catalog's entity types when [creating a new catalog](/ingesting-data-into-cortex/catalogs.md#create-custom-catalogs). Alternatively, [edit an existing catalog](/ingesting-data-into-cortex/catalogs.md#edit-catalogs) to add the type. ### Creating a custom entity type via the API You can create, update, and delete entity types using the [Cortex API](/api/readme/catalog-entities.md). Learn more about the [JSON schema](#json-schema-for-custom-entity-types). ## 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`
`required`	Required specs for the entity type
`properties`	Properties of the required specs (including `type`). Required when `required` is non-empty.	Conditional

### 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.

Adding attributes via JSON schema

When creating a custom entity in the Cortex UI, enter the entity's attribute values as JSON in the **Schema** field. Using the [example above](#json-schema-for-custom-entity-types), the schema format looks like: ```json { "location": "San Diego", "department": "Engineering" } ```

Adding attributes via YAML

For GitOps workflows or direct YAML editing in the Cortex UI, define the custom entity's metadata in the YAML. Using the [example above](#json-schema-for-custom-entity-types), the entity YAML looks like: ``` x-cortex-type: org-employees x-cortex-definition: location: San Diego department: Engineering ``` The `x-cortex-type` (the custom entity type) and the `x-cortex-definition` are required when creating a custom entity. 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 details page](/ingesting-data-into-cortex/entities-overview/entities/details.md). The schema and the defined properties appear under the **Overview** section on the entity's overview, making it easy for you to identify key specs. In the example below, the entity "Alabama" displays metadata for the property `location` :

The entity, "Alabama", displays metadata for the property 'location'.

To access an entity's details page, expand **All Catalogs** from the main sidebar, then select **All entities**. Select an entity to view its details. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.