# Data Catalog and Tracking Plans YAML Reference


This guide serves as a detailed reference for the CLI project YAML files that contain definitions of your Data Catalog and Tracking Plan resources.

## Overview

In the context of the Rudder CLI (`rudder-cli`) tool, a project typically consists of a root directory that contains all the project files. Within this root directory, each YAML file can contain definitions for resources of a particular type, for example, events, properties, custom data types, and Tracking Plans.

The location and naming of these YAML files is flexible, as you can store the YAML files anywhere within the project's root directory or subdirectories.

{{< info >}}
Every spec file must set the top-level field `version` to `rudder/v1`.
{{< /info >}}

You can also group some resources of the same type in the same file, allowing structures that can best serve your project's requirements. For example, you could have:

- A `events.yaml` file in the project's root directory that defines multiple events
- Another file `subdirectory/user-events.yaml` that defines additional events

{{< info >}}
The Rudder CLI tool processes all valid YAML files within the project structure to recognize the defined resources.
{{< /info >}}

The following sections detail the specific YAML formats and parameter definitions for each resource type.

For discriminator-based validation in Tracking Plan event rules and custom types, see the [Conditional Validation YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-data-catalog-and-tracking-plans/yaml-conditional-validation.md" >}}).

## Events

You can define one or more events in the YAML file by setting `kind` to `events`.

The `spec` parameter of the YAML file has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `events` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array of [event definitions](#event-definition) | An array of event definitions grouped together in the same file. |

### Event definition

The event definitions have a structure that depends on the event type. All definitions share some common properties, as listed in the below table:

| Property | Type | Description |
| :----| :-----| :------|
| `id ` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Unique identifier for the event within the project. This parameter must be unique across all events. |
| `event_type` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Event type. Acceptable values are `track`, `identify`, `page`, `screen`, and `group`. |
| `description` | String | Event description. |
| `category` | String | Reference to an existing [event category](#event-categories). <br /><br />See [Manage Event Categories using Rudder CLI]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/data-catalog/events.md#event-categories" >}}) for more information. |

Additionally, `track` events (`event_type: track`) also support the following property:

| Property | Type | Description |
| :----| :-----| :------|
| `name` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | The `track` event name. In other words, this parameter corresponds to the `event` property of the corresponding RudderStack `track` event. |

### Example {#event-example}

```yaml
version: rudder/v1
kind: events
metadata:
  name: myeventgroup
spec:
  events:
    - id: product_viewed
      name: "Product Viewed"
      event_type: track
      description: "This event is triggered every time a user views a product."
      category: "#category:browsing_category" # Reference to the Browsing category
    - id: added_to_cart
      name: "Added To Cart"
      event_type: track
      description: "This event is triggered every time the user adds a product to their cart."
    - id: identify
      event_type: identify
      description: "An event that identifies the user."
    - id: page
      event_type: page
```

{{% validation-rules-explorer kind="events" heading="Event validation rules" %}}

## Event categories

You can define event categories in the YAML file by setting `kind` to `categories`.

The `spec` parameter of the YAML file has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `categories` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array of [category definitions](#category-definition) | An array of category definitions grouped together in the same file. |

### Category definition

All category definitions share the following properties:

| Property | Type | Description |
| :----| :-----| :------|
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Unique identifier for the category within the project. This parameter must be unique across all categories in all the YAML files within the project. |
| `name` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Display name of the category. |

### Example {#category-example}

```yaml
version: rudder/v1
kind: categories
metadata:
  name: event-categories
spec:
  categories:
    - id: signup_category
      name: Signup
    - id: login_category
      name: Login
    - id: browsing_category
      name: Browsing
    - id: miscellaneous_category
      name: Miscellaneous
```

{{% validation-rules-explorer kind="categories" heading="Category validation rules" %}}

## Properties

You can define one or more properties in the YAML file by setting `kind` to `properties`.

The `spec` parameter of the YAML file has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `properties` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array of [property definitions](#property-definition) | An array of property definitions grouped together in the same file. |

### Property definition

A property definition has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Unique identifier for the property within the project. This parameter must be unique across all properties in all the YAML files within the project. |
| `name` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | This parameter corresponds to the field inside an event's `properties` or `traits` JSON. |
| `type` |  String | Set either `type` or `types` (not both). A single primitive type (`string`, `integer`, `number`, `object`, `array`, `boolean`, or `null`), or a URN reference to a custom type (`#custom-type:<id>`). |
| `types` | Array of strings | Set either `type` or `types` (not both). Use this when the property allows more than one primitive type. Each entry must be a primitive type name (not a custom type URN). |
| `item_type` | String | For `type: array`, set either `item_type` or `item_types` (not both). Describes a single type for each array element (primitive, or `#custom-type:<id>`). |
| `item_types` | Array of strings | For `type: array`, set either `item_type` or `item_types` (not both). Use when array elements can be one of several primitive types. |
| `description` |  String | Property description. |
| `config` | [`config`](#property-config) object | Additional validation rules for the property's values. Uses the same JSON Schema-style keywords as [`config` for custom types](#config-options), scoped to the property `type`. |

You must specify exactly one of `type` or `types`. For `type: array`, specify at most one of `item_type` or `item_types` to describe allowed element types.

#### Property config

| Property | Type | Description |
| :----| :-----| :------|
| `min_length` |  Integer | Minimum length of the property's string value. |
| `max_length` | Integer | Maximum length of the property's string value. |
| `pattern` |  String | Regular expression that the property's string values need to match with. |
| `enum` | Array of strings | List of all valid values for the property. |

Depending on the property `type`, you can use additional keywords in `config` with the same shapes as in [`config` options](#config-options) for custom types (for example `format`, `minimum`/`maximum`, or `min_items`/`max_items`).

### Example {#property-example}

```yaml
version: rudder/v1
kind: properties
metadata:
  name: ecommerce_properties
spec:
  properties:
    - id: product_id
      name: "product_id"
      type: string
      description: "Unique identifier for the product."
      config:
        min_length: 3
        max_length: 64
    - id: product_name
      name: "product_name"
      type: string
      description: "Name of the product."
      config:
        min_length: 2
        max_length: 255
    - id: product_price
      name: "product_price"
      type: number
      description: "Price of the product in the store's currency."
    - id: product_category
      name: "product_category"
      type: string
      description: "Category the product belongs to."
      config:
        enum:
        - "clothing"
        - "electronics"
        - "home_goods"
        - "beauty"
        - "accessories"
        max_length: 60
    - id: cart_items
      name: "cart_items"
      description: "Items present in the cart."
      type: array
      item_type: string
      config:
        min_items: 1
        unique_items: false
```

{{% validation-rules-explorer kind="properties" heading="Property validation rules" %}}

## Custom data types

You can define custom data types in the YAML file by setting `kind` to `custom-types`.

The `spec` parameter of the YAML file has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `types` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array of [custom type definitions](#custom-type-definition) | An array of custom type objects grouped together in the same file. |

### Custom type definition

| Property | Type | Description |
| :----| :-----| :------|
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Unique identifier for the custom type within the project. This parameter must be unique across all custom types in all the YAML files within the project. |
| `name` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Display name of the custom type. |
| `type` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> |  String | Base data type for the custom type. <br /><br /> Acceptable values are: `string`, `integer`, `number`, `object`, `array`, `boolean`. |
| `config` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | [`config`](#config-options) object | Validation rules for the custom type. The configuration options vary depending on the `type` parameter. |
| `description` |  String | Description of the custom type. |

#### `config` options

The `config` object's configuration varies depending on the `type` parameter.

{{< tabs tabTotal="3" >}}
{{% tab tabName="String" %}}
| Parameter | Description |
| :-----| :-----|
| `min_length` | Minimum string length |
| `max_length` | Maximum string length |
| `pattern` | Regular expression pattern |
| `format` | Predefined format like email, date, etc. |
| `enum` | Array of allowed values |
{{% /tab %}}
{{% tab tabName="Number/Integer" %}}
| Parameter | Description |
| :-----| :-----|
| `minimum` | Minimum value |
| `maximum` | Maximum value |
| `exclusive_minimum` | Exclusive minimum value |
| `exclusive_maximum` | Exclusive maximum value |
| `multiple_of` | Multiple of value |
{{% /tab %}}
{{% tab tabName="Array" %}}
| Parameter | Description |
| :-----| :-----|
| `item_types` | List of acceptable types for array items |
| `min_items` | Minimum number of items |
| `max_items` | Maximum number of items |
| `unique_items` | Boolean requiring uniqueness of items |
{{% /tab %}}
{{< /tabs >}}

### Example {#custom-type-example}

```yaml
version: rudder/v1
kind: custom-types
metadata:
  name: email-types
spec:
  types:
    - id: emailtype
      name: "EmailType"
      description: "Custom type for email validation"
      type: string
      config:
        format: "email"
        min_length: 5
        max_length: 255
        pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    - id: addresstype
      name: "AddressType"
      description: "Physical address information"
      type: object
      properties:
        - id: street
          type: string
          required: true
        - id: city
          type: string
          required: true
        - id: country
          type: string
          required: false
```

{{% validation-rules-explorer kind="custom-types" heading="Custom type validation rules" %}}

## Tracking Plans

You can define a Tracking Plan in the YAML file by setting `kind` to `tracking-plan`.

The `spec` parameter of the YAML file has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Unique identifier for the Tracking Plan within the project. This parameter must be unique across all the Tracking Plans in the project. |
| `display_name` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | A readable short name for the Tracking Plan. |
| `description` | String | Tracking plan description. |
| `rules` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array of [rules definitions](#rule-definition) | Contains the list of events in the Tracking Plan along with the rules for their expected properties. |

### Rules definition

| Property | Type | Description |
| :----| :-----| :------|
| `type` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | The rule type. The only acceptable value currently is `event_rule`.  |
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Rule ID. |
| `event` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | URN reference to an existing event definition. See [Reference catalog resources](#reference-catalog-resources) for more information. |
| `additional_properties` | Boolean | Validation rule that checks if the event can have properties other than those defined in the rule's `properties` section. <br /><br />**Default value**: `false` |
| `identity_section` <br/> <span style="color: #4D4DFF;font-size:12px;">Required, for non-track events</span> |  String | Defines in which field of the corresponding RudderStack event payload the rule's properties should be included. <br /><br />Acceptable values are: `properties`, `traits`, and `context.traits`. |
| `properties` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array of [rule property definitions](#rule-property-definition) | List of properties associated with the rule's event along with the validation rules for the Tracking Plan. |

#### Rule property definition

| Property | Type | Description |
| :----| :-----| :------|
| `property` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | URN reference to an existing property definition. <br /><br />See [Reference catalog resources](#reference-catalog-resources) for more information on how to work with references. |
| `required` | Boolean | Validation rule that determines whether the property should always be present in the RudderStack event. <br /><br />**Default value**: `false` |
| `properties` <br/> <span style="color: #4D4DFF;font-size:12px;">Applicable only for properties of `object` type</span> | Array of [rule property definitions](#rule-property-definition) | Defines which [nested properties]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/create.md#nested-properties" >}}) should be included when this property is used in the Tracking Plan. |

### Example {#tracking-plan-example}

```yaml
version: rudder/v1
kind: tracking-plan
metadata:
  name: ecommerce_tracking_plan
spec:
  id: ecommerce_tracking_plan
  display_name: "E-commerce Tracking Plan"
  description: "Tracking plan for an e-commerce application."
  rules:
    - type: event_rule
      id: product_viewed_rule
      event: "#event:product_viewed"
      additional_properties: false
      properties:
        - property: "#property:product_id"
          required: true
        - property: "#property:product_name"
          required: true
        - property: "#property:product_price"
          required: true
        - property: "#property:product_category"
          required: false
```

{{% validation-rules-explorer kind="tracking-plan,tp" heading="Tracking Plan validation rules" %}}

## Reference Catalog resources

Definitions in a YAML file can refer to definitions in other files by using URN reference strings — this is useful while defining resources like Tracking Plans which need to be associated with events and properties defined in other files.

References use the format `#<type>:<id>`, where `type` is the resource kind and `id` is the unique resource identifier.

For example:

```yaml
# Reference to an event
event: "#event:example_id"

# Reference to a property
property: "#property:example_property_id"

# Reference to a custom type
type: "#custom-type:example_type_id"

# Reference to a category
category: "#category:example_category_id"

# Reference to a Tracking Plan (for example, from Event Stream source governance)
tracking_plan: "#tracking-plan:example_tracking_plan_id"
```

## Import metadata {#import-metadata}

When you import resources from a workspace using the [`import workspace`]({{< ref "dev-tools/rudder-cli/import-resources/_index.md" >}}) command, the generated YAML files contain special import metadata that tells Rudder CLI how to link local resources to workspace resources.

### Structure

The import metadata is located in the `metadata.import` section of the YAML file:

```yaml
version: "rudder/v1"
kind: "categories"
metadata:
  import:
    workspaces:
      - workspace_id: "3NrueK2Hu7ooXVQqQJhKqKlnofE"
        resources:
          - local_id: "abc"
            remote_id: "cat_343HNkcWRt8YXHphthHwa8QEdXE"
          - local_id: "webapp"
            remote_id: "cat_2ohsVV9iKuw7GfLFITwsVLn6Nhy"
  name: "categories"
spec:
  categories:
    - id: "abc"
      name: "ABC"
    - id: "webapp"
      name: "Webapp"
```

### Properties

The `metadata.import` section contains the following properties:

| Property | Type | Description |
| :----| :-----| :------|
| `workspaces` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array | Array of workspace import configurations. Each workspace configuration contains the workspace ID and resource mappings. |

#### Workspace configuration

Each workspace configuration in the `workspaces` array has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `workspace_id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | The ID of the workspace where resources were imported from. |
| `resources` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array | Array of mappings between local resource IDs and their corresponding workspace IDs. |

#### Resource mapping

Each resource mapping in the `resources` array has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `local_id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | The local resource ID used within your CLI project. This corresponds to the `id` field in the resource definition. |
| `remote_id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | The remote resource ID from the workspace where the resource was imported from. |

{{< info >}}
The import metadata serves two key purposes:

- **Resource linking**: Enables Rudder CLI to link local resource definitions to existing workspace resources when you run the [`apply`]({{< ref "dev-tools/rudder-cli/import-resources/_index.md#apply-imported-resources" >}}) command.
- **Workspace-aware operations**: Tracks which workspace resources were imported from, allowing you to apply the same project to different workspaces. When you apply a project to a workspace different from the one specified in `workspace_id`, resources are treated as new resources to be created rather than imported.

See [Manage Workspaces]({{< ref "dev-tools/rudder-cli/import-resources/manage-workspaces" >}}) for more information about how to use import metadata in workspace management workflows.
{{< /info >}}