Conditional Validation YAML Reference Alpha

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

Available Plans

free
starter
growth
enterprise

4 minute read

Conditional validation involves using two kinds of variants:

Event Rule Variants within Tracking Plan event rules
Custom Type Variants within Custom Type definitions

Both types share a common structure but are used in different contexts. This reference details the YAML schema and configuration options for both types.

Common variant structure

All variant definitions share the following structure:

Property	Type	Description
`type` Required	String	Must be `discriminator`
`discriminator` Required	String	Full path of the property that determines which variant case applies. Must match a required property defined in the parent object.
`cases` Required	Array of case definitions	Array of variant cases defining different validation rules.
`default`	default case	Default validation rules when no case matches.

`cases` definition

Each case in the cases array has the following structure:

Property	Type	Description
`id` Required	String	Unique identifier for the case within the variant.
`display_name` Required	String	Human-readable name for the case.
`match` Required	Array	Array of values that trigger this case. Values must match the discriminator property’s type.
`description` Required	String	Description explaining when this case applies.
`properties`	Array of property references	Property requirements specific to this case.

`default` case

The optional default case has the following structure:

Property	Type	Description
`properties` Required	Array of property references	Property requirements for when no case matches.

Property references

Property references in both cases and default case have this structure:

Property	Type	Description
`$ref` Required	String	Reference to a property defined in the parent object’s properties section.
`required`	Boolean	Whether the property is required. Defaults to `false`.

Supported types

This section lists the types supported for the discriminator and match properties.

Discriminator types

The following types are supported for the discriminator property:

Type	Description	Example values	Notes
String	Text-based discrimination	`"search"`, `"US"`, `"clothing"`	Case-sensitive matching
Boolean	True/false discrimination	`true`, `false`	Simple binary choices
Number	Numeric discrimination	`500`, `1000`, `2000`	Exact value matching

The discriminator property must be:
Defined in the parent object’s properties section
Marked as required
Have a type matching your match values (string, boolean, or number)

Match values

The match array in each case supports:

Type	Format	Example
String	Array of strings	`["US", "USA", "United States"]`
Boolean	Array of booleans	`[true]` or `[false]`
Number	Array of numbers	`[500, 1000, 2000]`

Note that for match values:
RudderStack matches the values exactly (no pattern or range matching)
String matches are case-sensitive
Each case can have multiple match values
All match values in a case must be of the same type as the discriminator

Variant schemas

For validation purposes, RudderStack uses JSON Schema rules where variants is defined as an array of objects, each requiring type: discriminator.
The examples in the below section show the actual YAML structure.

See Event Rule Variants for usage details.

Event rules with variants must have allow_unplanned: false in their event definition.

variants:
  type: array
  items:
    type: object
    required:
      - type
      - discriminator
      - cases
    properties:
      type:
        type: string
        enum: [discriminator]
      discriminator:
        type: string
        pattern: "^#/<path_to_property>/.+$"
        description: "Full property path reference (e.g., #/properties/common_props/property_1)"
      cases:
        type: array
        items:
          type: object
          required:
            - id
            - display_name
            - match
            - description
          properties:
            id:
              type: string
            display_name:
              type: string
            match:
              type: array
              items:
                type: [string, boolean, number]
            description:
              type: string
            properties:
              type: array
              items:
                $ref: "#/definitions/property_reference"
      default:
        type: array
        items:
          $ref: "#/definitions/property_reference"

See Custom Type Variants for usage details.

types:
  type: array
  items:
    type: object
    required:
      - id
      - name
      - type
      - properties
    properties:
      id:
        type: string
      name:
        type: string
      type:
        type: string
        enum: [object]
      description:
        type: string
      properties:
        type: array
        items:
          $ref: "#/definitions/property_reference"
      variants:
        type: array
        items:
          type: object
          required:
            - type
            - discriminator
            - cases
          properties:
            type:
              type: string
              enum: [discriminator]
            discriminator:
              type: string
              pattern: "^#/<path_to_property>/.+$"
              description: "Full property path reference (e.g., #/properties/common_props/property_1)"
            cases:
              type: array
              items:
                type: object
                required:
                  - id
                  - display_name
                  - match
                  - description
                properties:
                  id:
                    type: string
                  display_name:
                    type: string
                  match:
                    type: array
                    items:
                      type: [string, boolean, number]
                  description:
                    type: string
                  properties:
                    type: array
                    items:
                      $ref: "#/definitions/property_reference"
            default:
              type: array
              items:
                $ref: "#/definitions/property_reference"

Variant structure examples

This section provides examples of how to define Event Rule and Custom Type variants using YAML configuration files.

Event Rule variant

variants:
  - type: discriminator
    discriminator: "page_type"
    cases:
      - id: search_page
        display_name: "Search Results Page"
        match: ["search", "search_results"]
        description: "When user is on search pages"
        properties:
          - $ref: "#/properties/search_term"
            required: true

Custom Type variant

variants:
  - type: discriminator
    discriminator: "country"
    cases:
      - id: us_address
        display_name: "US Address"
        match: ["US", "USA"]
        description: "US address format"
        properties:
          - $ref: "#/properties/state"
            required: true