Skip to main content

Service Descriptor

Every service in Cortex is described by a YAML file called the Cortex Service Descriptor, also referred to as a service's Cortex YAML (naturally stemming from cortex.yaml, which is filename that powers the GitOps approach!).

Getting Started

The Service Descriptor is a fully compliant OpenAPI 3 spec file, with our own Cortex-specific extentions that we've added.

You can still use Cortex if you don't use OpenAPI/Swagger!

We use the OpenAPI spec as a base for service metadata, since it's an open spec with official support for extensions. That lets us extend it to be a service descriptor spec with optional usage of actual OpenAPI fields.

The basics

A barebones spec file has the OpenAPI version, along with an info section that contains some basic details.

openapi: 3.0.0
title: My Service
x-cortex-tag: my-service
description: This is my cool service.

The only required fields under info are the title and the x-cortex-tag.

You'll see us refer to the "Service Tag" throughout the docs. The Service Tag is a unique identifier that's used through Cortex, for example to declare dependencies on other services or to look up information using the Slackbot.


Any time you see a mention of a Service Tag, we're referring the value of x-cortex-tag in the Service Descriptor.

Adding more information

Any additional metadata you want to add to your descriptor belongs in the info section. Throughout the docs, you'll see snippets that start with x-cortex-* – make sure to add this to the info section!


  1. Is this descriptor file only used for microservices?
    1. You can use Cortex to describe REST services, kafka consumers/producers, libraries, modules within a monolith, etc. Any entity that could be described as a logical module should live in Cortex.