Skip to main content
Every entity in your Cortex catalog is defined by a YAML file called the Cortex entity descriptor—often referred to as an entity’s Cortex YAML, after the cortex.yaml filename used in the GitOps approach. This applies whether you manage entities through the UI or GitOps; the descriptor is the underlying source of truth either way. Each descriptor is a fully compliant OpenAPI 3 spec file, extended with Cortex-specific fields that unlock additional functionality in your catalog.
You don’t need to use OpenAPI or Swagger to use Cortex. The OpenAPI spec serves as the foundation for entity metadata because it’s an open standard with official support for extensions, allowing Cortex to extend it into a full entity descriptor spec, while keeping the actual OpenAPI fields optional.

​
Metadata in entity descriptor YAML files

You can extend an entity by adding metadata to the info section of its descriptor. Throughout the docs, you’ll see snippets prefixed with x-cortex-*; these are descriptor blocks that belong inside info and unlock additional Cortex functionality.
YAML comments aren’t supported in entity descriptors. Cortex stores descriptors as JSON in the database, and JSON doesn’t support comments. Most YAML parsers also strip comments during round-tripping, so any comments added to a descriptor will be lost.

​
Required blocks

Every entity YAML requires the following:
BlockDescription
titleThe name of the entity
x-cortex-tagThe unique identifier for the entity
x-cortex-typeThe entity type

• If the entity is a custom type, you must also include x-cortex-definition
Although they aren’t required, it’s strongly recommended to add a description, groups, and owners:
BlockDefinition
descriptionA description of the entity
x-cortex-groupsThe entity’s groups - a tagging system used to segment entities

• Required field - tag
x-cortex-ownersThe entity’s owners

• Required field(s) - type, which can be group or email
• For group owners, name and provider are also required. The provider value is the integration the group comes from; use CORTEX for a team defined in Cortex.
• For email owners, email is also required
• inheritance - When creating a domain entity and adding owners to it, or while creating an entity relationship, you can set ownership inheritance under this block to pass down to the entity’s children. The inheritance type can be APPEND, FALLBACK, or NONE.

​
Additional basic metadata blocks

BlockDefinition
x-cortex-custom-metadataThe entity’s custom data

• Required fields - a key, value, and description. The key is the title for the custom data.
x-cortex-dependencyThe entity’s dependencies

• Required fields - tag. If method is included, then path is also required.
x-cortex-linkDocumentation links associated with the entity: name, type, and url
x-cortex-parents and
x-cortex-children		The entity’s parent entities and children entities

• Required field - tag
• These fields are supported for entities that are members of a hierarchical entity relationship, such as domains or teams
x-cortex-relationshipsA block that includes the entity’s relationship type and destination entities

• Required fields - type and destinations
x-cortex-teamThis appears in a team entity’s YAML. members can be defined under this block.

• A member is defined by name and email, and can also include notificationsEnabled and roles.

​
Integration metadata blocks

See the related linked documentation pages for instructions on adding metadata within each type of block.
Block
x-cortex-alertsOpsgenie
x-cortex-apiiroApiiro
x-cortex-apmDatadog, Dynatrace, New Relic
x-cortex-azureAzure Resources
x-cortex-azure-devopsAzure DevOps
x-cortex-bugsnagBugSnag
x-cortex-ci-cdBuildkite
x-cortex-checkmarxCheckmarx
x-cortex-circle-ciCircleCI
x-cortex-coralogixCoralogix
x-cortex-dashboardsCharts embedded from Datadog, Grafana, or New Relic
x-cortex-firehydrantFireHydrant
x-cortex-gitAzure DevOps, Bitbucket, GitHub, GitLab
x-cortex-incident-ioincident.io
x-cortex-infraAWS, Google
x-cortex-issuesClickUp, GitHub, Jira
x-cortex-k8sKubernetes
x-cortex-launch-darklyLaunchDarkly
x-cortex-microsoft-teamsMicrosoft Teams channels
x-cortex-oncallPagerDuty, Splunk On-Call (VictorOps), xMatters
x-cortex-ownersWhen you specify group as the type, you can use the following integrations as the group provider: BambooHR, Bitbucket, Entra ID (Azure AD), GitHub, GitLab, Google, Okta, ServiceNow, Workday
x-cortex-rollbarRollbar
x-cortex-rootlyRootly
x-cortex-sentrySentry
x-cortex-semgrepSemgrep
x-cortex-servicenowServiceNow
x-cortex-slackSlack channels
x-cortex-slosDatadog, Dynatrace, Google, Lightstep, Prometheus, Splunk Observability Cloud (SignalFX), Sumo Logic
x-cortex-snykSnyk
x-cortex-static-analysisCodecov, Mend, SonarQube, Veracode
x-cortex-wizWiz

​
Example entity YAML

The example below demonstrates how you can use each of the blocks in an entity’s YAML.
Last modified on September 21, 2026