Spec Version: v1 (Latest)v0.1

Data Catalog and Tracking Plans YAML Reference Beta

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.

Every spec file must set the top-level field version to rudder/v1.

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

The Rudder CLI tool processes all valid YAML files within the project structure to recognize the defined resources.

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.

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:

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:

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

Example

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

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:

Category definition

All category definitions share the following properties:

Example

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

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 definition

A property definition has the following structure:

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

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

Example

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

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:

Custom type definition

config options

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

Example

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

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:

Rules definition

Rule property definition

Example

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

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:

# 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

When you import resources from a workspace using the import workspace 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:

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:

Workspace configuration

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

Resource mapping

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

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 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 for more information about how to use import metadata in workspace management workflows.