RudderStack Docs – Conditional Validation in CLI-based Tracking Plan Management

Dev-Tools: Event Rule Variants

Mon, 01 Jan 0001 00:00:00 +0000

This guide shows you how to define and use event rule variants in your Tracking Plans.

Overview

Event rule variants let you define different property requirements for the same event based on a discriminating property value. This feature is particularly useful when an event needs different validation rules depending on the context in which it occurs.

Event rule variants use a discriminator field to determine which set of property requirements apply. The discriminator is a property whose value determines which variant case to use.

Define event rule variants

Using your preferred text editor, add variants to your event rules in the Tracking Plan YAML file:

Basic structure

Event rule variants are defined within event rules in Tracking Plans. See Conditional Validation YAML Reference for the detailed variant specification.

The following snippet is a simplified example to demonstrate the structure. See the Examples section below for real-world use cases with complete implementations.

version: rudder/v1
kind: tracking-plan
metadata:
 name: mytrackingplan
spec:
 rules:
 - type: event_rule
 id: example_rule
 event: "#event:example_event"
 additional_properties: false

 # Common properties for all variants
 properties:
 - property: "#property:property_1"
 required: true # Discriminator property must be required
 - property: "#property:property_2"
 required: false # Common property that may be required by variants
 - property: "#property:property_3"
 required: false # Property used in default case

 variants:
 - type: discriminator
 discriminator: "#property:property_1" # Must match the property defined above
 cases:
 - display_name: "Case A"
 match:
 - "value1"
 - "value2"
 description: "Description of Case A"
 properties:
 - property: "#property:property_2"
 required: true

 - display_name: "Case B"
 match:
 - "value3"
 description: "Description of Case B"
 properties:
 - property: "#property:property_2"
 required: true

 # Default case for unmatched values
 default:
 - property: "#property:property_3"
 required: true

Each variant definition requires:

The discriminator type (type: discriminator)
The discriminating property name (discriminator)
One or more cases with:
- A display name (display_name)
- Match values (match)
- Description (description) explaining when this case applies
- Property requirements (properties) specific to this case
Optional default case (default) for when no cases match

The discriminator property must be:

Defined in the event rule’s properties section

Marked as required

Have a type matching your match values (string, boolean, or number)

Supported discriminator types

You can use the following discriminator types in your event rule variants:

Type	Description	Example values
String	Match against text values	`"search"`, `"product"`, `"category_search"`
Boolean	Match true/false conditions	`true`, `false`
Number	Match against numeric thresholds	`500`, `1000`, `2000`

Note that for each type:

You can specify multiple match values in an array

Values are matched exactly (no range or pattern matching)

String matches are case-sensitive

Examples

The following examples show variant definitions for different use cases:

Use Case: Different property requirements based on page type

This example shows how to validate different properties based on which type of page the user is viewing (search, product, or checkout):

version: rudder/v1
kind: tracking-plan
metadata:
 name: ecommerce_tracking_plan
spec:
 rules:
 - type: event_rule
 id: page_viewed_rule
 event: "#event:page_viewed"
 additional_properties: false

 properties:
 - property: "#property:page_type"
 required: true
 - property: "#property:page_url"
 required: false

 variants:
 - type: discriminator
 discriminator: "#property:page_type"
 cases:
 - display_name: "Search Results Page"
 match:
 - "search"
 - "search_results"
 - "category_search"
 description: "When user is on search or category pages"
 properties:
 - property: "#property:search_term"
 required: true
 - property: "#property:search_filters"
 required: false

 - display_name: "Product Detail Page"
 match:
 - "product"
 - "product_detail"
 description: "When user is viewing a specific product"
 properties:
 - property: "#property:product_id"
 required: true
 - property: "#property:product_category"
 required: true
 - property: "#property:product_price"
 required: true
 - property: "#property:recommendation_source"
 required: false

 - display_name: "Checkout Flow Pages"
 match:
 - "checkout"
 - "payment"
 - "review_order"
 description: "When user is in checkout process"
 properties:
 - property: "#property:checkout_step"
 required: true
 - property: "#property:payment_method"
 required: false

 default:
 - property: "#property:page_url"
 required: true

Key takeaways

Uses string-based page type discrimination
Handles multiple match values per case (for example, search, search_results, category_search)
Shows required and optional properties for each page type
Includes a default case for unmatched page types

Use Case: Different requirements based on user subscription status

This example demonstrates how to validate different properties based on whether a user has premium access or not:

version: rudder/v1
kind: tracking-plan
metadata:
 name: user_management_plan
spec:
 rules:
 - type: event_rule
 id: feature_accessed_rule
 event: "#event:feature_accessed"
 additional_properties: false

 properties:
 - property: "#property:user_id"
 required: true
 - property: "#property:is_premium"
 required: true

 variants:
 - type: discriminator
 discriminator: "#property:is_premium"
 cases:
 - display_name: "Premium Users"
 match:
 - true
 description: "Premium subscribers with full access"
 properties:
 - property: "#property:subscription_tier"
 required: true
 - property: "#property:feature_access_level"
 required: true

 - display_name: "Free Users"
 match:
 - false
 description: "Free tier users with limitations"
 properties:
 - property: "#property:trial_days_remaining"
 required: false
 - property: "#property:usage_limit"
 required: true

Key takeaways

Uses simple boolean discrimination (true/false)
Shows different property requirements for premium vs. free users
Demonstrates required user identification for all cases
Shows how to handle optional properties like trial information

Use Case: Different requirements based on order total amount

This example shows how to validate different properties based on the order value, with special handling for high-value orders:

version: rudder/v1
kind: tracking-plan
metadata:
 name: order_tracking_plan
spec:
 rules:
 - type: event_rule
 id: order_placed_rule
 event: "#event:order_placed"
 additional_properties: false

 properties:
 - property: "#property:order_details"
 required: true
 - property: "#property:order_total"
 required: true

 variants:
 - type: discriminator
 discriminator: "#property:order_total"
 cases:
 - display_name: "High Value Orders"
 match:
 - 500
 - 1000
 - 2000
 description: "Orders above $500 threshold"
 properties:
 - property: "#property:loyalty_points_earned"
 required: true
 - property: "#property:vip_handling"
 required: true

 - display_name: "Standard Orders"
 match:
 - 50
 - 100
 - 200
 description: "Regular value orders"
 properties:
 - property: "#property:loyalty_points_earned"
 required: false

Key takeaways

Uses numeric value discrimination
Shows different thresholds for order value categories
Demonstrates special handling for high-value orders
Shows how to handle loyalty points based on order value

Best practices

Follow these best practices when defining event rule variants:

Discriminator selection
- Choose properties that clearly indicate different contexts
- Ensure the discriminator property is always available
- Use simple, predictable property values
Case definition
- Use clear, descriptive display names
- Group related match values in the same case
- Include helpful descriptions
Property requirements
- Include only relevant properties for each case
- Consider required vs. optional carefully
- Use default case for common requirements
Validation
- Test all variant cases
- Verify property references
- Check for edge cases

Validate and deploy variants

To update your Tracking Plans with the newly-added variants, make sure to validate and deploy the changes using Rudder CLI.

See the End-to-end Walkthrough for detailed steps on validating and deploying Tracking Plans.

Dev-Tools: Custom Type Variants

Mon, 01 Jan 0001 00:00:00 +0000

This guide shows you how to define and use custom type variants in your Data Catalog.

Overview

Custom type variants let you define different property requirements for reusable object types based on a discriminating property value. This feature is particularly useful when an object type needs different validation rules depending on the context in which it is used.

Custom type variants work similarly to Event Rule Variants but are defined at the custom type level rather than the event level. This makes them reusable across multiple events and Tracking Plans.

Define custom type variants

Using your preferred text editor, add variants to your custom types in the Custom Types YAML file:

Basic structure

Custom type variants are defined within custom type definitions. See Variants YAML Reference for the detailed variant specification.

The following snippet is a simplified example to demonstrate the structure. See the Examples section below for real-world use cases with complete implementations.

version: rudder/v1
kind: custom-types
metadata:
 name: mycustomtypes
spec:
 types:
 - id: custom_object
 name: "CustomObject"
 type: object
 description: "Object with context-specific requirements"

 # Common properties for all variants
 properties:
 - property: "#property:property_1"
 required: true # Discriminator property must be required
 - property: "#property:property_2"
 required: false # Common property that may be required by variants
 - property: "#property:property_3"
 required: false # Property used in default case

 variants:
 - type: discriminator
 discriminator: "#property:property_1" # Must match the property defined above
 cases:
 - display_name: "Case A"
 match:
 - "value1"
 - "value2"
 description: "Description of Case A"
 properties:
 - property: "#property:property_2"
 required: true

 - display_name: "Case B"
 match:
 - "value3"
 description: "Description of Case B"
 properties:
 - property: "#property:property_2"
 required: true

 # Default case for unmatched values
 default:
 - property: "#property:property_3"
 required: true

Each variant definition requires:

The discriminator type (type: discriminator)
The discriminating property name (discriminator)
One or more cases with:
- A display name (display_name)
- Match values (match)
- Description (description) explaining when this case applies
- Property requirements (properties) specific to this case
Optional default case (default) for when no cases match

The discriminator property must be:

Defined in the custom type’s properties section

Marked as required

Have a type matching your match values (string, boolean, or number)

Supported discriminator types

You can use the following discriminator types in your custom type variants:

Type	Description	Example values
String	Match against text values	`"US"`, `"UK"`, `"Japan"`
Boolean	Match true/false conditions	`true`, `false`
Number	Match against numeric thresholds	`500`, `1000`, `2000`

Note that for each type:

You can specify multiple match values in an array

Values are matched exactly (no range or pattern matching)

String matches are case-sensitive

Examples

The following examples show variant definitions for different use cases:

Use Case: Different address requirements based on country/region

This example shows how to validate different properties based on the country code, with specific requirements for each region:

version: rudder/v1
kind: custom-types
metadata:
 name: address_types
spec:
 types:
 - id: address_object
 name: "AddressObject"
 type: object
 description: "Address with region-specific requirements"

 properties:
 - property: "#property:country"
 required: true
 - property: "#property:street_address"
 required: true
 - property: "#property:city"
 required: true
 - property: "#property:postal_code"
 - property: "#property:state_province"
 - property: "#property:prefecture"
 - property: "#property:district"

 variants:
 - type: discriminator
 discriminator: "#property:country"
 cases:
 - display_name: "US Address"
 match:
 - "US"
 - "USA"
 - "United States"
 description: "US address format with state and ZIP"
 properties:
 - property: "#property:state_province"
 required: true
 - property: "#property:postal_code"
 required: true

 - display_name: "UK Address"
 match:
 - "UK"
 - "GB"
 - "United Kingdom"
 description: "UK address format with postcode"
 properties:
 - property: "#property:postal_code"
 required: true

 - display_name: "Japan Address"
 match:
 - "JP"
 - "Japan"
 description: "Japanese address format with prefecture"
 properties:
 - property: "#property:prefecture"
 required: true
 - property: "#property:district"
 required: false

 default:
 - property: "#property:postal_code"
 required: false

Key takeaways

Uses string-based country code discrimination
Handles multiple country codes per case (for example, US, USA, United States)
Shows region-specific address requirements
Includes optional fields like district for specific regions

Use Case: Different product attributes based on category

This example shows how to validate different properties based on the product category:

version: rudder/v1
kind: custom-types
metadata:
 name: product_types
spec:
 types:
 - id: product_object
 name: "ProductObject"
 type: object
 description: "Product with category-specific attributes"

 properties:
 - property: "#property:product_id"
 required: true
 - property: "#property:product_name"
 required: true
 - property: "#property:category"
 required: true
 - property: "#property:price"
 required: true
 - property: "#property:size"
 - property: "#property:color"
 - property: "#property:material"
 - property: "#property:brand"
 - property: "#property:model"
 - property: "#property:screen_size"
 - property: "#property:storage_capacity"
 - property: "#property:author"
 - property: "#property:isbn"
 - property: "#property:page_count"

 variants:
 - type: discriminator
 discriminator: "#property:category"
 cases:
 - display_name: "Clothing & Apparel"
 match:
 - "clothing"
 - "apparel"
 - "fashion"
 - "shoes"
 - "accessories"
 description: "Clothing items with size, color, material"
 properties:
 - property: "#property:size"
 required: true
 - property: "#property:color"
 required: true
 - property: "#property:material"
 required: false
 - property: "#property:brand"
 required: true

 - display_name: "Electronics"
 match:
 - "electronics"
 - "computers"
 - "phones"
 - "tablets"
 - "gadgets"
 description: "Electronic devices with technical specs"
 properties:
 - property: "#property:brand"
 required: true
 - property: "#property:model"
 required: true
 - property: "#property:screen_size"
 required: false
 - property: "#property:storage_capacity"
 required: false

 - display_name: "Books & Literature"
 match:
 - "books"
 - "ebooks"
 - "literature"
 - "textbooks"
 description: "Books with author and publishing details"
 properties:
 - property: "#property:author"
 required: true
 - property: "#property:isbn"
 required: false
 - property: "#property:page_count"
 required: false

 default:
 - property: "#property:brand"
 required: false

Key takeaways

Uses category-based discrimination
Shows different property sets for each product type
Handles optional technical specifications
Demonstrates category-specific validation rules
Includes default case for brand property

Use Case: Different profile requirements based on account type

This example shows how to validate different properties based on the user’s account type:

version: rudder/v1
kind: custom-types
metadata:
 name: user_profile_types
spec:
 types:
 - id: user_profile_object
 name: "UserProfileObject"
 type: object
 description: "User profile with subscription-based requirements"

 properties:
 - property: "#property:user_id"
 required: true
 - property: "#property:email"
 required: true
 - property: "#property:account_type"
 required: true
 - property: "#property:first_name"
 - property: "#property:last_name"
 - property: "#property:company_name"
 - property: "#property:job_title"
 - property: "#property:phone_number"
 - property: "#property:billing_address"
 - property: "#property:tax_id"
 - property: "#property:contract_start_date"
 - property: "#property:account_manager"

 variants:
 - type: discriminator
 discriminator: "#property:account_type"
 cases:
 - display_name: "Individual Account"
 match:
 - "individual"
 - "personal"
 - "consumer"
 description: "Personal individual accounts"
 properties:
 - property: "#property:first_name"
 required: true
 - property: "#property:last_name"
 required: true
 - property: "#property:phone_number"
 required: false

 - display_name: "Enterprise Account"
 match:
 - "enterprise"
 - "premium"
 - "platinum"
 description: "Enterprise accounts with full details"
 properties:
 - property: "#property:company_name"
 required: true
 - property: "#property:job_title"
 required: true
 - property: "#property:phone_number"
 required: true
 - property: "#property:billing_address"
 required: true
 - property: "#property:tax_id"
 required: true
 - property: "#property:contract_start_date"
 required: true
 - property: "#property:account_manager"
 required: true

 default:
 - property: "#property:first_name"
 required: false
 - property: "#property:last_name"
 required: false

Key takeaways

Uses account type discrimination
Shows progressive property requirements (individual > business > enterprise)
Demonstrates enterprise-specific fields like contract details
Includes comprehensive profile validation with default case
Shows how to handle optional vs. required fields per account type

Best practices

Follow these best practices when defining custom type variants:

Discriminator selection
- Choose properties that clearly indicate different contexts
- Ensure the discriminator property is always available
- Use simple, predictable property values
Case definition
- Use clear, descriptive display names
- Group related match values in the same case
- Include helpful descriptions
Property requirements
- Include only relevant properties for each case
- Consider required vs. optional carefully
- Use default case for common requirements
Validation
- Test all variant cases
- Verify property references
- Check for edge cases

Validate and deploy variants

To update your custom types with the newly-added variants, make sure to validate and deploy the changes using Rudder CLI.

Reference custom types in properties

Once defined, you can use custom types with variants in your properties:

version: rudder/v1
kind: properties
metadata:
 name: integration_properties
spec:
 properties:
 - id: customer_profile
 name: "customer_profile"
 type: "#custom-type:user_profile_object"
 description: "Customer profile information"
 - id: purchased_product
 name: "purchased_product"
 type: "#custom-type:product_object"
 description: "Product that was purchased"
 - id: shipping_address
 name: "shipping_address"
 type: "#custom-type:address_object"
 description: "Where to ship the order"

You can then reference these properties in your Tracking Plan:

version: rudder/v1
kind: tracking-plan
metadata:
 name: integrated_tracking_plan
spec:
 id: integrated_plan
 display_name: "Integrated Plan with Custom Types"
 description: "Tracking plan demonstrating custom type usage"
 rules:
 - type: event_rule
 id: purchase_completed_rule
 event: "#event:purchase_completed"
 additional_properties: false

 properties:
 - property: "#property:customer_profile"
 required: true
 - property: "#property:purchased_product"
 required: true
 - property: "#property:shipping_address"
 required: true

RudderStack Docs – Conditional Validation in CLI-based Tracking Plan Management

Dev-Tools: Event Rule Variants

Overview

Define event rule variants

Basic structure

Supported discriminator types

Examples

Key takeaways

Key takeaways

Key takeaways

Best practices

Validate and deploy variants

See also

Dev-Tools: Custom Type Variants

Overview

Define custom type variants

Basic structure

Supported discriminator types

Examples

Key takeaways

Key takeaways

Key takeaways

Best practices

Validate and deploy variants

Reference custom types in properties

See also