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

        
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. Alternatively, edit an existing catalog to add the type.

Creating a custom entity type via the API

You can create, update, and delete entity types using the Cortex API. Learn more about the JSON schema.

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

{
  "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, the schema format looks like:

{
    "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, 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.

Metadata in the entity details page

Defining a JSON schema enables visibility on an entity's details page. 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 :

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.