# Data Catalog and Tracking Plans YAML Reference > Complete reference for defining your Data Catalog and Tracking Plan resources using YAML configuration files. 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`. 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. 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](https://www.rudderstack.com/docs/rudder-cli/yaml-data-catalog-and-tracking-plans/yaml-conditional-validation/). ## 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](#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 `
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](#event-categories).

See [Manage Event Categories using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/data-catalog/events/#event-categories) 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 {#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 ``` ### Event validation rules
Spec version
Filter by phase

Showing 5 of 5 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 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 yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed_2
      event_type: track
      name: Page Viewed
Diagnostics
  • spec.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 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 yaml 
version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed_2
      event_type: track
      name: Page Viewed
Diagnostics
  • spec.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 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 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 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 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 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 oneof

URNs must be unique across the project

syntactic errorAll spec versions

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic errorAll spec versions

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic errorAll spec versions

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' is required
## 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](#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`
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 {#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 ``` ### Category validation rules
Spec version
Filter by phase

Showing 5 of 5 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 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 yaml 
version: rudder/v1
kind: categories
metadata:
  name: my-categories
spec:
  categories:
    - id: user_actions_2
      name: User Actions
Diagnostics
  • spec.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 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 yaml 
version: rudder/0.1
kind: categories
metadata:
  name: my-categories
spec:
  categories:
    - id: user_actions_2
      name: User Actions
Diagnostics
  • spec.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 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 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 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 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

URNs must be unique across the project

syntactic errorAll spec versions

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic errorAll spec versions

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic errorAll spec versions

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' 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](#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`
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:`). | | `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:`). | | `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 ``` ### Property validation rules
Spec version
Filter by phase

Showing 6 of 6 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 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 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 totally_wrong

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 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 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 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 not_valid

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 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 yaml 
version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id_2
      name: User ID
      type: string
Diagnostics
  • spec.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 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 yaml 
version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id_2
      name: User ID
      type: string
Diagnostics
  • spec.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 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 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 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 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 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

URNs must be unique across the project

syntactic errorAll spec versions

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic errorAll spec versions

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic errorAll spec versions

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' 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](#custom-type-definition) | 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`](#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. #### 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 | #### 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 | #### 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 | ### 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 ``` ### Custom type validation rules
Spec version
Filter by phase

Showing 6 of 6 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 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 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 not_a_valid_format

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 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 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 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 invalid_format

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 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 yaml 
version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address_v2
      name: Address
      type: object
Diagnostics
  • spec.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 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 yaml 
version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address_v2
      name: Address
      type: object
Diagnostics
  • spec.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 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 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 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 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 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

URNs must be unique across the project

syntactic errorAll spec versions

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic errorAll spec versions

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic errorAll spec versions

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' 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](#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`
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](#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](#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`
Required | String | URN reference to an existing property definition.

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.

**Default value**: `false` | | `properties`
Applicable only for properties of `object` type | Array of [rule property definitions](#rule-property-definition) | Defines which [nested properties](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/create/#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 ``` ### Tracking Plan validation rules
Spec version
Filter by phase

Showing 5 of 5 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)

spec.yaml 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.

spec.yaml 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'

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)

spec.yaml 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.

spec.yaml 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'

Tracking Plan spec syntax must be valid

syntactic error

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

Examples

Valid Tracking Plan spec

spec.yaml 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 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 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 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

URNs must be unique across the project

syntactic errorAll spec versions

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic errorAll spec versions

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic errorAll spec versions

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' 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 `#:`, 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`](https://www.rudderstack.com/docs/rudder-cli/import-resources/) 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`
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. | **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`](https://www.rudderstack.com/docs/rudder-cli/import-resources/#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](https://www.rudderstack.com/docs/rudder-cli/import-resources/manage-workspaces/) for more information about how to use import metadata in workspace management workflows.