# Conditional Validation YAML Reference


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



**Announcement**

The **Conditional Validation** feature is in **Private Beta** as part of RudderStack's [Early Access Program](https://www.rudderstack.com/docs/get-started/introduction/alpha-and-beta-features/beta-features/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](mailto:support@rudderstack.com) if you are interested in enabling this feature for your workspace.

[Conditional validation](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/) involves using two kinds of variants:

- [Event Rule Variants](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/event-rules/) within Tracking Plan event rules
- [Custom Type Variants](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/custom-type-rules/) within [Custom Type](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/data-catalog/custom-types/) 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.

## Manage variants

You can manage variants only through YAML and Rudder CLI. After conditional validation is enabled for your workspace, the RudderStack dashboard is read-only for variants — you can view variants but cannot create, edit, or delete them in the RudderStack dashboard.

## Common variant structure

All variant definitions share the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `type`  <br/> Required| String | Must be `discriminator` |
| `discriminator` <br/> Required | String | URN reference to the discriminating property, in the form **`#property:<id>`**. Must match a required property from the parent object's `properties` list. <br /><br />See [Reference catalog resources](https://www.rudderstack.com/docs/rudder-cli/yaml-data-catalog-and-tracking-plans/#reference-catalog-resources). |
| `cases` <br/> Required | Array of [case definitions](#case-definition) | Array of variant cases defining different validation rules. |
| `default` | [default case](#default-case) | Default validation rules when no case matches. |

### Case definition {#case-definition}

Each case in the `cases` array has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `display_name` <br/> Required | String | Human-readable name for the case. |
| `match` <br/> Required | Array | Array of values that trigger this case. Values must match the discriminator property's type. |
| `description` <br/> Required | String | Description explaining when this case applies. |
| `properties` | Array of [property references](#property-references) | Property requirements specific to this case. |

### Default case {#default-case}

The optional default case has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `properties` <br/> Required | Array of [property references](#property-references) | Property requirements for when no case matches. |

### Property references {#property-references}

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

| Property | Type | Description |
| :----| :-----| :------|
| `property` <br/> Required | String | URN reference to a property definition using **`#property:<id>`**, consistent with Tracking Plan rules and custom types. The property must be listed 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 |

**Info**

The discriminator property must be:

- Defined in the parent object&#39;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]` |

**Info**

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 structure examples

This section provides examples of how to define [Event Rule](#event-rule-variant) and [Custom Type](#custom-type-variant) variants using YAML configuration files.

### Event Rule variant {#event-rule-variant}

```yaml
variants:
  - type: discriminator
    discriminator: "#property:page_type"
    cases:
      - display_name: "Search Results Page"
        match: ["search", "search_results"]
        description: "When user is on search pages"
        properties:
          - property: "#property:search_term"
            required: true
```

### Custom Type variant {#custom-type-variant}

```yaml
variants:
  - type: discriminator
    discriminator: "#property:country"
    cases:
      - display_name: "US Address"
        match: ["US", "USA"]
        description: "US address format"
        properties:
          - property: "#property:state_province"
            required: true
```

## See also

- [Data Catalog and Tracking Plans YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-data-catalog-and-tracking-plans/#reference-catalog-resources)
- [Event Rule Variants](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/event-rules/)
- [Custom Type Variants](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/custom-type-rules/)

<br />