Select spec version:

Custom Type Variants Beta

Define reusable object types with context-specific property requirements using custom type variants.

  •   7 minute read  

The Custom data types feature is in Private Beta, where we work with early users and customers to test new features and get feedback before making them generally available.

Reach out to Customer Success if you are interested in enabling this feature for your workspace.

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.

yaml
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:

TypeDescriptionExample values
StringMatch against text values"US", "UK", "Japan"
BooleanMatch true/false conditionstrue, false
NumberMatch against numeric thresholds500, 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:

yaml
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

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:

yaml
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:

yaml
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

See also


Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.

Slack community Join now Email support Reach out