# Conditional Validation YAML Reference


{{< announcement >}}
The **Conditional Validation** feature is in **Private Beta** as part of RudderStack's [Early Access Program]({{< ref "get-started/introduction/alpha-and-beta-features/beta-features/private-beta.md" >}}), 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.
{{< /announcement >}}

[Conditional validation]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/" >}}) involves using two kinds of variants:

- [Event Rule Variants]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/event-rules" >}}) within Tracking Plan event rules
- [Custom Type Variants]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/custom-type-rules" >}}) within [Custom Type]({{< ref "dev-tools/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/> <span style="color: #4D4DFF;font-size:12px;">Required</span>| String | Must be `discriminator` |
| `discriminator` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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]({{< ref "dev-tools/rudder-cli/yaml-data-catalog-and-tracking-plans/_index.md#reference-catalog-resources" >}}). |
| `cases` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Human-readable name for the case. |
| `match` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Array | Array of values that trigger this case. Values must match the discriminator property's type. |
| `description` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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's properties section
- Marked as required
- Have a type matching your match values (string, boolean, or number)
{{< /info >}}

### 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
{{< /info >}}

## 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]({{< ref "dev-tools/rudder-cli/yaml-data-catalog-and-tracking-plans/_index.md#reference-catalog-resources" >}})
- [Event Rule Variants]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/event-rules" >}})
- [Custom Type Variants]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/conditional-validation/custom-type-rules" >}})

<br />