Get a DemoCortex AcademyWebsiteStatusLogin

Defining entities via YAML file

Whether you use the UI or GitOps to manage entities, every entity in your Cortex catalogs is defined by a YAML file called the Cortex entity descriptor, also referred to as an entity's Cortex YAML (stemming from cortex.yaml, the name of the file that powers the GitOps approach.)

Each file is a fully compliant OpenAPI 3 spec file, with our own Cortex-specific extensions.

You can still use Cortex if you don't use OpenAPI/Swagger. We use the OpenAPI spec as a base for entity metadata, since it's an open spec with official support for extensions. That lets us extend it to be an entity descriptor spec with optional usage of actual OpenAPI fields.

Metadata in entity descriptor YAML files

The metadata you add to your descriptor belongs in the info section of the YAML file.

Throughout the Cortex docs, you'll see metadata examples that start with x-cortex-* – these belong in the info section of your entity YAMLs.

Note that it is not currently supported to include comments in YAML files.

Required blocks

Every entity YAML requires the following:

Recommended blocks

Although they aren't required, we recommend adding a description, groups, and owners:

  • description: A description of the entity

  • x-cortex-groups: The entity's groups - a tagging system used to segment entities

    • Required field: tag

  • x-cortex-owners: The entity's owners

    • Required field: type

    • Owners can be defined by group from an ownership integration or by email address.

    • 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

  • x-cortex-custom-metadata: The entity's custom data

    • Required fields: a key, value, and description. The key is the title for the custom data.

  • x-cortex-dependency: The entity's dependencies

    • Required fields: tag. If method is included, then path is also required.

  • x-cortex-link: Documentation links associated with the entity

    • name, type, and url

  • x-cortex-parents and x-cortex-children: The entity's parent entities and children entities.

  • x-cortex-relationships: A block that includes the entity's relationship type and destination entities.

    • Required fields: type and destinations

  • x-cortex-team: This appears in a team entity's YAML. Under this block you can define members.

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

Example entity YAML

The example below demonstrates how you can use each of the blocks in an entity's YAML file.

Last updated

Was this helpful?