# Event Stream Source YAML Reference


This guide serves as a detailed reference for the CLI project YAML files that contain definitions of your Event Stream source resources.

## Overview

In the context of the Rudder CLI (`rudder-cli`) tool, you can define Event Stream sources as YAML files within your project directory. The location and naming of these YAML files is flexible, as you can store the YAML files anywhere within the project's root directory or subdirectories.

{{< info >}}
The Rudder CLI tool processes all valid YAML files within the project structure to recognize the defined resources.
{{< /info >}}

## Event Stream Sources

You can define an Event Stream source in the YAML file by setting `kind` to `event-stream-source`.

The `spec` parameter of the YAML file has the following structure:

| Property | Type | <div style="width:300px">Description</div> |
| :----| :-----| :------|
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Unique identifier for the source within the project. This parameter must be unique across all sources in the project. |
| `type` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Source type identifier. See [Supported source types](#supported-source-types) for the list of acceptable values. |
| `name` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Name for the source. It must be non-empty. |
| `enabled` | Boolean | Determines whether this source is accepting events. <br /><br />**Default value**: `true` |
| `governance` | [Data governance configuration](#data-governance-configuration) object | Contains data governance-related settings for the source. |

### Data governance configuration

The `governance` object contains validation settings that control how the source handles any Tracking Plan violations:

| Property | Type | <div style="width:300px">Description</div> |
| :----| :-----| :------|
| `validations` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | [Validation properties](#validation-properties) object | Contains validation configuration including Tracking Plan reference and violation rules. |

### Validation properties

The `validations` object contains the Tracking Plan reference and violation handling rules:

| Property | Type | <div style="width:300px">Description</div> |
| :----| :-----| :------|
| `tracking_plan` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | URN reference to a Tracking Plan resource — the format is `#tracking-plan:[tracking-plan.id]`, where `tracking-plan.id` is the `spec.id` value of the Tracking Plan resource. |
| `config` | [Violation rules configuration](#violation-rules-configuration) object | Contains violation rules for all event types. If not specified, default violation rules apply to all event types. |

{{< info >}}
You must have a [Tracking Plan defined in your CLI project]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/" >}}) before you can reference it in a source configuration.

See [CLI-based Tracking Plan Management]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/create.md" >}}) for more information on creating Tracking Plans.
{{< /info >}}

### Violation rules configuration

The `config` object contains violation handling rules for different event types. Each event type configuration is optional; if not specified, default violation rules apply:

| Property | Type | <div style="width:300px">Description</div> |
| :----| :-----| :------|
| `track` | [Violation rules](#violation-rules-properties) object | Violation rules for `track` events. |
| `identify` | [Violation rules](#violation-rules-properties) object | Violation rules for `identify` events. |
| `group` | [Violation rules](#violation-rules-properties) object | Violation rules for `group` events. |
| `page` | [Violation rules](#violation-rules-properties) object | Violation rules for `page` events. |
| `screen` | [Violation rules](#violation-rules-properties) object | Violation rules for `screen` events. |

### Violation rules properties

Each violation rules object contains the following properties:

| Property | Type | <div style="width:300px">Description</div> |
| :----| :-----| :------|
| `propagate_violations` | Boolean | Determines whether to add violations in event context. When enabled, violation information is included in the event payload's context for downstream processing. <br /><br />**Default value**: `true` |
| `drop_unplanned_events` | Boolean | **Only applies to `track` configuration.** Determines whether to drop events without a corresponding rule in the associated Tracking Plan. <br /><br />**Default value**: `false` |
| `drop_unplanned_properties` | Boolean | Determines whether to drop properties that are not defined in the Tracking Plan for the event. <br /><br />**Default value**: `false` |
| `drop_other_violations` | Boolean | Determines whether to drop events with any other validation violations. <br /><br />**Default value**: `false` |

{{< warning >}}
If you set `drop_unplanned_events`, `drop_unplanned_properties`, or `drop_other_violations` to `true`, events that violate these rules are dropped and not forwarded to destinations.

Make sure you understand the impact of these settings before deploying your source configuration.
{{< /warning >}}

{{% validation-rules-explorer kind="event-stream-source" heading="Validation rules" %}}

## Supported source types

The following table lists all supported source types and their corresponding `type` values:

| Source | `type` value |
|------------|-------------|
| Java | `java` |
| .NET | `dotnet` |
| PHP | `php` |
| Flutter | `flutter` |
| Cordova | `cordova` |
| Rust | `rust` |
| React Native | `react_native` |
| Python | `python` |
| iOS | `ios` |
| Android | `android` |
| JavaScript | `javascript` |
| Go | `go` |
| Node | `node` |
| Ruby | `ruby` |
| Unity | `unity` |

## Examples

#### Basic source configuration

This example shows a minimal source configuration without governance settings:

```yaml
version: rudder/v1
kind: event-stream-source
metadata:
  name: ios-source
spec:
  id: "my-ios-source"
  type: "ios"
  name: "iOS Source"
  enabled: true
```

#### Source with governance configuration

This example shows a source with governance configuration that links to a Tracking Plan and defines violation rules for different event types:

```yaml
version: rudder/v1
kind: event-stream-source
metadata:
  name: ios-source
spec:
  id: "my-ios-source"
  type: "ios"
  name: "iOS Source"
  enabled: true
  governance:
    validations:
      tracking_plan: "#tracking-plan:ecommerce-tracking-plan"
      config:
        track:
          propagate_violations: true
          drop_unplanned_events: true
          drop_unplanned_properties: true
          drop_other_violations: true
        identify:
          propagate_violations: true
          drop_unplanned_properties: true
          drop_other_violations: true
        group:
          propagate_violations: true
          drop_unplanned_properties: true
          drop_other_violations: true
        page:
          propagate_violations: true
          drop_unplanned_properties: true
          drop_other_violations: true
        screen:
          propagate_violations: true
          drop_unplanned_properties: true
          drop_other_violations: true
```

#### Source with partial governance configuration

This example shows a source that only defines violation rules for `track` events, letting other event types use default rules:

```yaml
version: rudder/v1
kind: event-stream-source
metadata:
  name: web-source
spec:
  id: "my-web-source"
  type: "javascript"
  name: "Web Source"
  enabled: true
  governance:
    validations:
      tracking_plan: "#tracking-plan:web-tracking-plan"
      config:
        track:
          propagate_violations: false
          drop_unplanned_events: false
          drop_unplanned_properties: false
          drop_other_violations: false
```

#### Disabled source

This example shows a source that is disabled and does not accept events:

```yaml
version: rudder/v1
kind: event-stream-source
metadata:
  name: test-source
spec:
  id: "test-source"
  type: "python"
  name: "Test Source"
  enabled: false
```

## Reference Tracking Plans

When configuring data governance validation, you can reference [Tracking Plans]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/" >}}) using the following URN format:

```yaml
tracking_plan: "#tracking-plan:[tracking-plan.id]"
```

Where `tracking-plan.id` is the `spec.id` value of the Tracking Plan.

For example, if your Tracking Plan YAML file looks like this:

```yaml
version: rudder/v1
kind: tracking-plan
metadata:
  name: ecommerce-tracking-plan
spec:
  id: product-tracking-plan
  display_name: "Product Tracking Plan"
  # ... rest of the configuration
```

You would reference it in your source configuration as:

```yaml
tracking_plan: "#tracking-plan:product-tracking-plan"
```

## See more

- See [Manage Event Stream Sources using Rudder CLI]({{< ref "dev-tools/rudder-cli/event-stream-sources" >}}) for feature overview, and the [Event Stream Sources walkthrough]({{< ref "dev-tools/rudder-cli/event-stream-sources-walkthrough" >}}) for step-by-step setup
- See [CLI-based Tracking Plan Management]({{< ref "dev-tools/rudder-cli/data-catalog-and-tracking-plans/tracking-plans" >}}) to create the Tracking Plans that you can reference in your Event Stream source configurations
- See [Data Catalog and Tracking Plans YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-data-catalog-and-tracking-plans" >}}) for information about Tracking Plan YAML structure
- See [Manage Destinations using Rudder CLI]({{< ref "dev-tools/rudder-cli/destinations.md" >}}) and [Connection YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-connections.md" >}}) to send events from this source to a destination

<br />