Spec Version:

Data Catalog and Tracking Plans YAML Reference Beta

Complete reference for defining your Data Catalog and Tracking Plan resources using YAML configuration files.

Available Plans

free
growth
enterprise

23 minute read

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:

Property	Type	Description
`events` Required	Array of event definitions	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` Required	String	Unique identifier for the event within the project. This parameter must be unique across all events.
`event_type` Required	String	Event type. Acceptable values are `track`, `identify`, `page`, `screen`, and `group`.
`description`	String	Event description.
`category`	String	Reference to an existing event category. See Manage Event Categories using Rudder CLI for more information.

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

Property	Type	Description
`name` Required	String	The `track` event name. In other words, this parameter corresponds to the `event` property of the corresponding RudderStack `track` event.

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 validation rules

Event references must resolve to existing resources

semantic error

Rule ID: datacatalog/events/semantic-valid

Examples

Unique event name and type combinations (v1)

spec.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
    - id: product_clicked
      event_type: track
      name: Product Clicked

Duplicate event name and type across files (v1)

Duplicate event name and event_type pairs in the resource graph fail validation.

spec.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed

spec2.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events-2
spec:
  events:
    - id: page_viewed_copy
      event_type: track
      name: Page Viewed

Diagnostics

spec.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'
spec2.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'

Event references must resolve to existing resources

semantic error

Rule ID: datacatalog/events/semantic-valid

Examples

Unique event name and type combinations (legacy)

spec.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
    - id: product_clicked
      event_type: track
      name: Product Clicked

Duplicate event name and type across files (legacy)

Duplicate event name and event_type pairs in the resource graph fail validation.

spec.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed

spec2.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events-2
spec:
  events:
    - id: page_viewed_copy
      event_type: track
      name: Page Viewed

Diagnostics

spec.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'
spec2.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'

Event spec syntax must be valid

syntactic error

Rule ID: datacatalog/events/spec-syntax-valid

Examples

Valid events spec

spec.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
    - id: user_identified
      event_type: identify

v1 event missing required event_type field

spec.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      name: Page Viewed

Diagnostics

spec.yaml /events/0/event_type 'event_type' is required

Event spec syntax must be valid

syntactic error

Rule ID: datacatalog/events/spec-syntax-valid

Examples

Valid legacy events spec

spec.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
      description: User viewed a page
    - id: user_identified
      event_type: identify

Legacy event missing required id field

spec.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - name: Page Viewed
      event_type: track

Diagnostics

spec.yaml /events/0/id 'id' is required

Legacy event with invalid event_type

spec.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: my_event
      event_type: custom

Diagnostics

spec.yaml /events/0/event_type 'event_type' must be one of [track screen identify group 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:

Property	Type	Description
`categories` Required	Array of category definitions	An array of category definitions grouped together in the same file.

Category definition

All category definitions share the following properties:

Property	Type	Description
`id` Required	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` Required	String	Display name of the category.

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

Category validation rules

Category names must be unique across the Data Catalog

semantic error

Rule ID: datacatalog/categories/semantic-valid

Examples

Unique category names (v1)

spec.yaml

version: rudder/v1
kind: categories
metadata:
  name: my-categories
spec:
  categories:
    - id: user_actions
      name: User Actions
    - id: system_events
      name: System Events

Duplicate category names across files (v1)

Duplicate category names in the resource graph fail validation.

spec.yaml

version: rudder/v1
kind: categories
metadata:
  name: my-categories
spec:
  categories:
    - id: user_actions
      name: User Actions

spec2.yaml

version: rudder/v1
kind: categories
metadata:
  name: my-categories-2
spec:
  categories:
    - id: user_actions_copy
      name: User Actions

Diagnostics

spec.yaml /categories/0/name duplicate name 'User Actions' within kind 'categories'
spec2.yaml /categories/0/name duplicate name 'User Actions' within kind 'categories'

Category names must be unique across the Data Catalog

semantic error

Rule ID: datacatalog/categories/semantic-valid

Examples

Unique category names (legacy)

spec.yaml

version: rudder/0.1
kind: categories
metadata:
  name: my-categories
spec:
  categories:
    - id: user_actions
      name: User Actions
    - id: system_events
      name: System Events

Duplicate category names across files (legacy)

Duplicate category names in the resource graph fail validation.

spec.yaml

version: rudder/0.1
kind: categories
metadata:
  name: my-categories
spec:
  categories:
    - id: user_actions
      name: User Actions

spec2.yaml

version: rudder/0.1
kind: categories
metadata:
  name: my-categories-2
spec:
  categories:
    - id: user_actions_copy
      name: User Actions

Diagnostics

spec.yaml /categories/0/name duplicate name 'User Actions' within kind 'categories'
spec2.yaml /categories/0/name duplicate name 'User Actions' within kind 'categories'

Category spec syntax must be valid

syntactic error

Rule ID: datacatalog/categories/spec-syntax-valid

Examples

Valid categories spec

spec.yaml

version: rudder/v1
kind: categories
metadata:
  name: categories
spec:
  categories:
    - id: user_actions
      name: User Actions
    - id: system_events
      name: System Events

Category missing required name field

spec.yaml

version: rudder/v1
kind: categories
metadata:
  name: categories
spec:
  categories:
    - id: user_actions

Diagnostics

spec.yaml /spec/categories/0/name 'name' is required

Category spec syntax must be valid

syntactic error

Rule ID: datacatalog/categories/spec-syntax-valid

Examples

Valid legacy categories spec

spec.yaml

version: rudder/0.1
kind: categories
metadata:
  name: legacy-categories
spec:
  categories:
    - id: user_actions
      name: User Actions
    - id: system_events
      name: System Events

Legacy category missing required name field

spec.yaml

version: rudder/0.1
kind: categories
metadata:
  name: legacy-categories
spec:
  categories:
    - id: user_actions

Diagnostics

spec.yaml /spec/categories/0/name 'name' is required

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` Required	Array of property definitions	An array of property definitions grouped together in the same file.

Property definition

A property definition has the following structure:

Property	Type	Description
`id` Required	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` Required	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` object	Additional validation rules for the property’s values. Uses the same JSON Schema-style keywords as `config` for custom types, 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 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

Property validation rules

Property config must be valid for the given type

syntactic error

Rule ID: datacatalog/properties/config-valid

Examples

Valid string property config

spec.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      config:
        format: "email"
        min_length: 5

v1 string property config with invalid format

spec.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      config:
        format: totally_wrong

Diagnostics

spec.yaml /properties/0/propConfig/format 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

Property config must be valid for the given type

syntactic error

Rule ID: datacatalog/properties/config-valid

Examples

Valid string property config with format (legacy)

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      propConfig:
        format: "email"
        minLength: 5
        maxLength: 100

Valid integer property config with range (legacy)

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: age
      name: Age
      type: integer
      propConfig:
        minimum: 0
        maximum: 120

String property config with invalid format (legacy)

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      propConfig:
        format: not_valid

Diagnostics

spec.yaml /properties/0/propConfig/format 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

Property references must resolve to existing resources

semantic error

Rule ID: datacatalog/properties/semantic-valid

Examples

Unique property name and type combinations (v1)

spec.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string
    - id: email
      name: Email
      type: string

Duplicate property name, type, and itemTypes across files (v1)

Duplicate property name, type, and itemTypes in the resource graph fail validation.

spec.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string

spec2.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties-2
spec:
  properties:
    - id: user_id_copy
      name: User ID
      type: string

Diagnostics

spec.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'
spec2.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'

Property references must resolve to existing resources

semantic error

Rule ID: datacatalog/properties/semantic-valid

Examples

Unique property name and type combinations (legacy)

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string
    - id: email
      name: Email
      type: string

Duplicate property name, type, and itemTypes across files (legacy)

Duplicate property name, type, and itemTypes in the resource graph fail validation.

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string

spec2.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties-2
spec:
  properties:
    - id: user_id_copy
      name: User ID
      type: string

Diagnostics

spec.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'
spec2.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'

Property spec syntax must be valid

syntactic error

Rule ID: datacatalog/properties/spec-syntax-valid

Examples

Valid properties spec

spec.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string
    - id: age
      name: Age
      type: integer

v1 property missing required id field

spec.yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - name: User ID
      type: string

Diagnostics

spec.yaml /properties/0/id 'id' is required

Property spec syntax must be valid

syntactic error

Rule ID: datacatalog/properties/spec-syntax-valid

Examples

Valid legacy properties spec

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      description: Unique identifier for the user
      type: string
    - id: email
      name: Email
      type: string

Legacy property missing required id field

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - name: User ID
      type: string

Diagnostics

spec.yaml /properties/0/id 'id' is required

Legacy property missing required name field

spec.yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      type: string

Diagnostics

spec.yaml /properties/0/name 'name' is required

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` Required	Array of custom type definitions	An array of custom type objects grouped together in the same file.

Custom type definition

Property	Type	Description
`id` Required	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` Required	String	Display name of the custom type.
`type` Required	String	Base data type for the custom type. Acceptable values are: `string`, `integer`, `number`, `object`, `array`, `boolean`.
`config` Required	`config` 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.

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

Parameter	Description
`minimum`	Minimum value
`maximum`	Maximum value
`exclusive_minimum`	Exclusive minimum value
`exclusive_maximum`	Exclusive maximum value
`multiple_of`	Multiple of value

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

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

Custom type validation rules

Custom type config must be valid for the given type

syntactic error

Rule ID: datacatalog/custom-types/config-valid

Examples

Valid string config with pattern

spec.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_status
      name: UserStatus
      type: string
      config:
        enum: ["active", "inactive"]

v1 string config with invalid format

spec.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_email
      name: UserEmail
      type: string
      config:
        format: not_a_valid_format

Diagnostics

spec.yaml /types/0/config/format 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

Custom type config must be valid for the given type

syntactic error

Rule ID: datacatalog/custom-types/config-valid

Examples

Valid string config with enum (legacy)

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_status
      name: UserStatus
      type: string
      config:
        enum: ["active", "inactive"]
        pattern: "^[a-z]+$"

Valid integer config with range (legacy)

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: age
      name: Age
      type: integer
      config:
        minimum: 0
        maximum: 120

String config with invalid format (legacy)

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_email
      name: UserEmail
      type: string
      config:
        format: invalid_format

Diagnostics

spec.yaml /types/0/config/format 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

Custom type references must resolve to existing resources

semantic error

Rule ID: datacatalog/custom-types/semantic-valid

Examples

Unique custom type names (v1)

spec.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object
    - id: user_status
      name: UserStatus
      type: string

Duplicate custom type names across files (v1)

Duplicate custom type names in the resource graph fail validation.

spec.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object

spec2.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types-2
spec:
  types:
    - id: address_copy
      name: Address
      type: object

Diagnostics

spec.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'
spec2.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'

Custom type references must resolve to existing resources

semantic error

Rule ID: datacatalog/custom-types/semantic-valid

Examples

Unique custom type names (legacy)

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object
    - id: user_status
      name: UserStatus
      type: string

Duplicate custom type names across files (legacy)

Duplicate custom type names in the resource graph fail validation.

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object

spec2.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types-2
spec:
  types:
    - id: address_copy
      name: Address
      type: object

Diagnostics

spec.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'
spec2.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'

Custom type spec syntax must be valid

syntactic error

Rule ID: datacatalog/custom-types/spec-syntax-valid

Examples

Valid custom-types spec

spec.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object
    - id: user_status
      name: UserStatus
      type: string

v1 custom type missing required id field

spec.yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - name: UserStatus
      type: string

Diagnostics

spec.yaml /types/0/id 'id' is required

Custom type spec syntax must be valid

syntactic error

Rule ID: datacatalog/custom-types/spec-syntax-valid

Examples

Valid legacy custom-types spec

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      description: Physical address structure
      type: object
    - id: user_status
      name: UserStatus
      type: string

Legacy custom type missing required name field

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_status
      type: string

Diagnostics

spec.yaml /types/0/name 'name' is required

Legacy custom type missing required type field

spec.yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address

Diagnostics

spec.yaml /types/0/type 'type' is required

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` Required	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` Required	String	A readable short name for the Tracking Plan.
`description`	String	Tracking plan description.
`rules` Required	Array of rules definitions	Contains the list of events in the Tracking Plan along with the rules for their expected properties.

Rules definition

Property	Type	Description
`type` Required	String	The rule type. The only acceptable value currently is `event_rule`.
`id` Required	String	Rule ID.
`event` Required	String	URN reference to an existing event definition. See 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. Default value: `false`
`identity_section` Required, for non-track events	String	Defines in which field of the corresponding RudderStack event payload the rule’s properties should be included. Acceptable values are: `properties`, `traits`, and `context.traits`.
`properties` Required	Array of rule property definitions	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` Required	String	URN reference to an existing property definition. See 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. Default value: `false`
`properties` Applicable only for properties of `object` type	Array of rule property definitions	Defines which nested properties should be included when this property is used in the Tracking Plan.

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

Tracking Plan validation rules

Tracking Plan references must resolve to existing resources

semantic error

Rule ID: datacatalog/tracking-plans/semantic-valid

Examples

Tracking Plan with unique display_name (v1)

The referenced event exists in the catalog, so the Tracking Plan validates cleanly.

events.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup

spec.yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event: "#event:signup"

Duplicate Tracking Plan display_name across files (v1)

Duplicate Tracking Plan display_name values in the resource graph fail validation.

events.yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup
    - id: page_view
      event_type: track
      name: Page View

spec.yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event: "#event:signup"

spec2.yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan-2
spec:
  id: my_tp_2
  display_name: My Tracking Plan
  rules:
    - id: page_rule
      type: event_rule
      event: "#event:page_view"

Diagnostics

spec.yaml /display_name duplicate display_name 'My Tracking Plan' within kind 'tracking-plan'
spec2.yaml /display_name duplicate display_name 'My Tracking Plan' within kind 'tracking-plan'

Tracking Plan references must resolve to existing resources

semantic error

Rule ID: datacatalog/tracking-plans/semantic-valid

Examples

Tracking Plan with unique display_name (legacy)

The referenced event exists in the catalog, so the Tracking Plan validates cleanly.

events.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup

spec.yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/signup"

Duplicate Tracking Plan display_name across files (legacy)

Duplicate Tracking Plan display_name values in the resource graph fail validation.

events.yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup
    - id: page_view
      event_type: track
      name: Page View

spec.yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/signup"

spec2.yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan-2
spec:
  id: my_tp_2
  display_name: My Tracking Plan
  rules:
    - id: page_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/page_view"

Diagnostics

spec.yaml /display_name duplicate display_name 'My Tracking Plan' within kind 'tp'
spec2.yaml /display_name duplicate display_name 'My Tracking Plan' within kind 'tp'

Tracking Plan spec syntax must be valid

syntactic error

Rule ID: datacatalog/tracking-plans/spec-syntax-valid

Examples

Valid Tracking Plan spec

spec.yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event: "#event:signup"
      properties:
        - property: "#property:user_id"
          required: true

Tracking Plan rule missing event field

spec.yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: no_event_rule
      type: event_rule
      properties:
        - property: "#property:user_id"
          required: true

Diagnostics

spec.yaml /rules/0/event 'event' is required

Tracking Plan spec syntax must be valid

syntactic error

Rule ID: datacatalog/tracking-plans/spec-syntax-valid

Examples

Valid legacy Tracking Plan spec

spec.yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/signup"
      properties:
        - $ref: "#/properties/common/user_id"
          required: true

Legacy Tracking Plan rule missing event field

spec.yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: no_event_rule
      type: event_rule
      properties:
        - $ref: "#/properties/common/user_id"
          required: true

Diagnostics

spec.yaml /rules/0/event 'event' is required

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:

Property	Type	Description
`workspaces` Required	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` Required	String	The ID of the workspace where resources were imported from.
`resources` Required	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` Required	String	The local resource ID used within your CLI project. This corresponds to the `id` field in the resource definition.
`remote_id` Required	String	The remote resource ID from the workspace where the resource was imported from.

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.

Conditional Validation YAML Reference

Complete reference for defining Event Rule and Custom Type variants using YAML configuration files.

Data Catalog and Tracking Plans YAML Reference Beta

Overview

Events

Event definition

Example

Event validation rules

Event references must resolve to existing resources

Examples

Unique event name and type combinations (v1)

Duplicate event name and type across files (v1)

Event references must resolve to existing resources

Examples

Unique event name and type combinations (legacy)

Duplicate event name and type across files (legacy)

Event spec syntax must be valid

Examples

Valid events spec

v1 event missing required event_type field

Event spec syntax must be valid

Examples

Valid legacy events spec

Legacy event missing required id field

Legacy event with invalid event_type

Event categories

Category definition

Example

Category validation rules

Category names must be unique across the Data Catalog

Examples

Unique category names (v1)

Duplicate category names across files (v1)

Category names must be unique across the Data Catalog

Examples

Unique category names (legacy)

Duplicate category names across files (legacy)

Category spec syntax must be valid

Examples

Valid categories spec

Category missing required name field

Category spec syntax must be valid

Examples

Valid legacy categories spec

Legacy category missing required name field

Properties

Property definition

Property config

Example

Property validation rules

Property config must be valid for the given type

Examples

Valid string property config

v1 string property config with invalid format

Property config must be valid for the given type

Examples

Valid string property config with format (legacy)

Valid integer property config with range (legacy)

String property config with invalid format (legacy)

Property references must resolve to existing resources

Examples

Unique property name and type combinations (v1)

Duplicate property name, type, and itemTypes across files (v1)

Property references must resolve to existing resources

Examples

Unique property name and type combinations (legacy)

Duplicate property name, type, and itemTypes across files (legacy)

Property spec syntax must be valid

Examples

Valid properties spec

v1 property missing required id field

Property spec syntax must be valid

Examples

Valid legacy properties spec

Legacy property missing required id field

Legacy property missing required name field

Custom data types

Custom type definition

config options

Example

Custom type validation rules

Custom type config must be valid for the given type

`config` options