---
title: "Schema Reference"
url: https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/schema-reference/
description: "Learn in detail about the pre-defined schema definitions of the catalyst-pipelines.yaml file."
last_updated: 2026-08-28T06:26:16Z
service: Pipelines
type: general
---

# Schema Reference  

The YAML schema reference for Catalyst Pipelines outlines the pre-defined keys for various components of the pipeline. By using these keys, you can incorporate the necessary components and define the execution flow of the pipeline.
We will be discussing the components in detail in their respective help pages. You can get started from [here](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/runners/). Refer to [this page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/implementation) to learn more about configuring the pipeline from the Catalyst console. 

### YAML Definitions

Here's the list of keys supported in Catalyst for the `catalyst-pipelines.yaml` file.

<table class="content-table">
        <thead>
            <tr>
                <th>Keyword</th>
                <th>Description</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>`version`</td>
                <td>The pipeline version can be defined as any integer value, serving the purpose of preserving pipeline configurations as distinct and reusable versions.</td>
            </tr>
            <tr>
                <td>`runners`</td>
                <td>A runner is a virtual machine configuration that can be defined at the **stage** level or **job** level. You can define the runner specification as a value of the `config-id` key in `runners`. Learn more about this detail from [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/runners).</td>
            </tr>
            <tr>
                <td>`images`</td>
                <td>An image is a package or set of dependencies required for the execution of jobs in the pipeline. Images can be defined at the **stage** level or **job** level. 

You can define the name of the image in the `image` key and the URL of the external package registry (like Dockerhub) in the `registry` key. 
            
You must also define the `auth` key to authenticate the specified registry. Learn more about this detail from [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images).
</td>
            </tr>
            <tr>
                <td>`auth`</td>
                <td>To authenticate any external registry accounts and pull the required packages for job execution, you will need to specify the `username` and `password` keys in the `auth` key. You can refer to [this help section](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images) to know more about this.</td>
            </tr>
            <tr>
                <td>`variables`</td>
                <td>This keyword is used to store placeholder values at the **pipeline** level or **job** level. Check out [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/variables) for more details.</td>
            </tr>
            <tr>
                <td>`steps`</td>
                <td>They are a set of commands that can be defined to carry out the build, test, and deploy processes in the pipeline. You can define the steps based on the applications you build, the testing procedures for it, and the environments in which the application has to be deployed. Refer to [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/steps) to learn more about steps.</td>
            </tr>
            <tr>
                <td>`jobs`</td>
                <td>A job is a sequence of steps defined in a stage. You can define up to five jobs within a stage, and under each job, you can define `steps`, `variables`, `runners`, and `images` using the `jobs` key.

If you have configured the pipeline to build your application before testing or deploying it, you can temporarily store the generated build files of your code in the Catalyst Stratus service. These configurations can be defined using the `artifacts` key.

This key includes two other sub-keys named `notify` and `approve`.

You can learn more about this in detail from [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/jobs/introduction). 
</td>
            </tr>
            <tr>
                <td>`notify`</td>
                <td>This key allows you to send notifications either at the start of job execution or upon successful completion of the job. You can use the `on-start` or `on-end` keys for this purpose. Check out [this help section](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/jobs/introduction) for more details.</td>
            </tr>
            <tr>
                <td>`approve`</td>
                <td>This key is used for [approval jobs](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/jobs/introduction) to define the details of the job reviewer and the custom approval message.

You can set the approval type using the `type-name` sub-key and add the email address of the reviewer and a custom review message in the `type-variables` key that includes the `reviewers` and `message` sub-keys, respectively.
</td>
            </tr>
            <tr>
                <td>`artifacts`</td>
                <td>This key is used to represent the upload and download process of the application build files generated during pipeline execution. For this, you can set the values in the `upload` and `download` keys respectively. You can learn more about artifacts from [ its help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/artifacts). </td>
            </tr>
            <tr>
                <td>`upload`</td>
                <td>This key is used to store the generated build zip files in the Catalyst Stratus service. You must define the name of the build file, the location in which the file has to be stored, and other file conditions using the `name`, `location`, and `files` sub-keys respectively.</td>
            </tr>
            <tr>
                <td>`download`</td>
                <td>This key can be used to retrieve the stored build zip files from the Catalyst Stratus service. You can also define the `name`, `location`, and `files` sub-keys similar to the upload keyword.</td>
            </tr>
            <tr>
                <td>`[stages](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/stages)`</td>
                <td>A stage is a distinct phase that contains multiple jobs in it. You can define up to five stages in a pipeline, each containing a set of jobs. You can also define `runners` and `images` at the stage level.</td>
            </tr>
            <tr>
                <td>`[when-equal](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-equal)`</td>
                <td>This key can be used to evaluate whether two values exactly match with one another and proceed with the specified execution flow of the pipeline, only if the validation holds true.</td>
            </tr>
            <tr>
                <td>`[when-not](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-not)`</td>
                <td>This key can be used to evaluate whether a particular condition is either `true` or `false`. Based on the result of the evaluation, the defined pipeline flow will be executed.</td>
            </tr>
            <tr>
                <td>`[when-not-equal](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-not-equal)`</td>
                <td>This key can be used to evaluate whether two values do not match with one another, then proceed with executing the defined pipeline flow.</td>
            </tr>
            <tr>
                <td>`[when-and](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-andwhen-or)`</td>
                <td>This key can be used to evaluate whether the two conditions defined in the `and` key hold true. If yes, then the flow defined in the `when` condition gets executed.</td>
            </tr>
            <tr>
                <td>`[when-or](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-andwhen-or)`</td>
                <td>This key can be used to evaluate whether either one of the conditions defined in the `or` key holds true. If yes, then the pipeline flow defined in the `when` key gets executed.</td>
            </tr>
            <tr>
                <td>`[pipeline-when](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#global-configuration)`</td>
                <td>The conditional logic that can be defined at the pipeline level, which dictates the execution flow of the whole pipeline. You can use the `and`, `equal`, `or`, `not`, `not-equal` key along with the `pipeline-when` condition.</td>
            </tr>
            <tr>
                <td>`[pipeline-runner](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/runners/#global-configuration)`</td>
                <td>This key can be used to define a runner at the pipeline level, which is accessible across all stages and jobs.</td>
            </tr>
            <tr>
                <td>`[pipeline-image](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images/#global-configuration)`</td>
                <td>This key can be used to define an image at the pipeline level, which is accessible across all stages and jobs.</td>
            </tr>
            </tbody>
</table>

> **Note:** When defining the pipeline execution flow in the [pipeline-image](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images/#global-configuration)
 file, ensure to utilize the exact keywords designated by Catalyst as keys and assign the corresponding data to each key.
Keyword	Description
`version`	The pipeline version can be defined as any integer value, serving the purpose of preserving pipeline configurations as distinct and reusable versions.
`runners`	A runner is a virtual machine configuration that can be defined at the stage level or job level. You can define the runner specification as a value of the `config-id` key in `runners`. Learn more about this detail from [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/runners).
`images`	An image is a package or set of dependencies required for the execution of jobs in the pipeline. Images can be defined at the stage level or job level. You can define the name of the image in the `image` key and the URL of the external package registry (like Dockerhub) in the `registry` key. You must also define the `auth` key to authenticate the specified registry. Learn more about this detail from [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images).
`auth`	To authenticate any external registry accounts and pull the required packages for job execution, you will need to specify the `username` and `password` keys in the `auth` key. You can refer to [this help section](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images) to know more about this.
`variables`	This keyword is used to store placeholder values at the pipeline level or job level. Check out [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/variables) for more details.
`steps`	They are a set of commands that can be defined to carry out the build, test, and deploy processes in the pipeline. You can define the steps based on the applications you build, the testing procedures for it, and the environments in which the application has to be deployed. Refer to [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/steps) to learn more about steps.
`jobs`	A job is a sequence of steps defined in a stage. You can define up to five jobs within a stage, and under each job, you can define `steps`, `variables`, `runners`, and `images` using the `jobs` key. If you have configured the pipeline to build your application before testing or deploying it, you can temporarily store the generated build files of your code in the Catalyst Stratus service. These configurations can be defined using the `artifacts` key. This key includes two other sub-keys named `notify` and `approve`. You can learn more about this in detail from [this help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/jobs/introduction).
`notify`	This key allows you to send notifications either at the start of job execution or upon successful completion of the job. You can use the `on-start` or `on-end` keys for this purpose. Check out [this help section](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/jobs/introduction) for more details.
`approve`	This key is used for [approval jobs](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/jobs/introduction) to define the details of the job reviewer and the custom approval message. You can set the approval type using the `type-name` sub-key and add the email address of the reviewer and a custom review message in the `type-variables` key that includes the `reviewers` and `message` sub-keys, respectively.
`artifacts`	This key is used to represent the upload and download process of the application build files generated during pipeline execution. For this, you can set the values in the `upload` and `download` keys respectively. You can learn more about artifacts from [ its help page](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/artifacts).
`upload`	This key is used to store the generated build zip files in the Catalyst Stratus service. You must define the name of the build file, the location in which the file has to be stored, and other file conditions using the `name`, `location`, and `files` sub-keys respectively.
`download`	This key can be used to retrieve the stored build zip files from the Catalyst Stratus service. You can also define the `name`, `location`, and `files` sub-keys similar to the upload keyword.
`[stages](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/stages)`	A stage is a distinct phase that contains multiple jobs in it. You can define up to five stages in a pipeline, each containing a set of jobs. You can also define `runners` and `images` at the stage level.
`[when-equal](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-equal)`	This key can be used to evaluate whether two values exactly match with one another and proceed with the specified execution flow of the pipeline, only if the validation holds true.
`[when-not](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-not)`	This key can be used to evaluate whether a particular condition is either `true` or `false`. Based on the result of the evaluation, the defined pipeline flow will be executed.
`[when-not-equal](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-not-equal)`	This key can be used to evaluate whether two values do not match with one another, then proceed with executing the defined pipeline flow.
`[when-and](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-andwhen-or)`	This key can be used to evaluate whether the two conditions defined in the `and` key hold true. If yes, then the flow defined in the `when` condition gets executed.
`[when-or](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#when-andwhen-or)`	This key can be used to evaluate whether either one of the conditions defined in the `or` key holds true. If yes, then the pipeline flow defined in the `when` key gets executed.
`[pipeline-when](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/when-condition/#global-configuration)`	The conditional logic that can be defined at the pipeline level, which dictates the execution flow of the whole pipeline. You can use the `and`, `equal`, `or`, `not`, `not-equal` key along with the `pipeline-when` condition.
`[pipeline-runner](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/runners/#global-configuration)`	This key can be used to define a runner at the pipeline level, which is accessible across all stages and jobs.
`[pipeline-image](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images/#global-configuration)`	This key can be used to define an image at the pipeline level, which is accessible across all stages and jobs.