# Event Stream Source YAML Reference > Complete reference for defining Event Stream sources using YAML configuration files. 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. ## 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 |
Description
| | :----| :-----| :------| | `id`
Required | String | Unique identifier for the source within the project. This parameter must be unique across all sources in the project. | | `type`
Required | String | Source type identifier. See [Supported source types](#supported-source-types) for the list of acceptable values. | | `name`
Required | String | Name for the source. It must be non-empty. | | `enabled` | Boolean | Determines whether this source is accepting events.

**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 |
Description
| | :----| :-----| :------| | `validations`
Required | [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 |
Description
| | :----| :-----| :------| | `tracking_plan`
Required | 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](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/) before you can reference it in a source configuration. See [CLI-based Tracking Plan Management](https://www.rudderstack.com/docs/rudder-cli/data-catalog-and-tracking-plans/tracking-plans/create/) for more information on creating Tracking Plans. ### 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 |
Description
| | :----| :-----| :------| | `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 |
Description
| | :----| :-----| :------| | `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.

**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.

**Default value**: `false` | | `drop_unplanned_properties` | Boolean | Determines whether to drop properties that are not defined in the Tracking Plan for the event.

**Default value**: `false` | | `drop_other_violations` | Boolean | Determines whether to drop events with any other validation violations.

**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. ### Validation rules
Spec version
Filter by phase

Showing 5 of 5 rules

Event Stream source references must resolve to existing resources

semantic error

Rule ID: event-stream/source/semantic-valid

Examples

Valid source without governance

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My Python Source
  type: python

Valid source with an existing Tracking Plan reference

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My Python Source
  type: python
  governance:
    validations:
      tracking_plan: "#tracking-plan:tp-main"
      config: {}
tracking_plan.yaml yaml 
version: rudder/v1
kind: tracking-plan
metadata:
  name: tp-main
spec:
  id: tp-main
  name: Main Tracking Plan
  description: Default plan
  rules: []

v1 source references a missing Tracking Plan

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My Python Source
  type: python
  governance:
    validations:
      tracking_plan: "#tracking-plan:tp-missing"
      config: {}
Diagnostics
  • spec.yaml /governance/validations/tracking_plan not found in the project

v1 source name duplicates another source in the project

source-a.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: source-a
spec:
  id: src-a
  name: Shared Name
  type: javascript
source-b.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: source-b
spec:
  id: src-b
  name: Shared Name
  type: node
Diagnostics
  • source-a.yaml /name duplicate name 'Shared Name' within kind 'event-stream-source'

V1 sources whose names differ only in case (names compare case-insensitively)

source-a.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: source-a
spec:
  id: src-a
  name: Web App
  type: javascript
source-b.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: source-b
spec:
  id: src-b
  name: web app
  type: node
Diagnostics
  • source-a.yaml /name duplicate name 'Web App' (case-insensitive match with 'web app') within kind 'event-stream-source'
  • source-b.yaml /name duplicate name 'web app' (case-insensitive match with 'Web App') within kind 'event-stream-source'

Event Stream source references must resolve to existing resources

semantic error

Rule ID: event-stream/source/semantic-valid

Examples

Valid legacy source without governance

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My JavaScript Source
  type: javascript

Valid legacy source with an existing Tracking Plan reference

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My JavaScript Source
  type: javascript
  governance:
    validations:
      tracking_plan: "#/tp/my-group/tp-main"
      config: {}
tracking_plan.yaml yaml 
version: rudder/0.1
kind: tracking-plan
metadata:
  name: tp-main
spec:
  id: tp-main
  name: Main Tracking Plan
  description: Default plan
  rules: []

Legacy source references a missing Tracking Plan

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My JavaScript Source
  type: javascript
  governance:
    validations:
      tracking_plan: "#/tp/my-group/tp-missing"
      config: {}
Diagnostics
  • spec.yaml /governance/validations/tracking_plan not found in the project

Legacy source name duplicates another source in the project

source-a.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: source-a
spec:
  id: src-a
  name: Shared Name
  type: javascript
source-b.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: source-b
spec:
  id: src-b
  name: Shared Name
  type: node
Diagnostics
  • source-a.yaml /name duplicate name 'Shared Name' within kind 'event-stream-source'

Event Stream source spec syntax must be valid

syntactic error

Rule ID: event-stream/source/spec-syntax-valid

Examples

Valid source spec with required fields

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-python-source
spec:
  id: src-py-1
  name: My Python Source
  type: python

Valid source spec with Tracking Plan governance

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-android-source
spec:
  id: src-android-1
  name: My Android Source
  type: android
  governance:
    validations:
      tracking_plan: "#tracking-plan:tp-main"
      config: {}

v1 source spec missing required name

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  type: javascript
Diagnostics
  • spec.yaml /name 'name' is required

v1 source spec with legacy Tracking Plan reference format

spec.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My Source
  type: javascript
  governance:
    validations:
      tracking_plan: "#/tp/my-group/tp-1"
      config: {}
Diagnostics
  • spec.yaml /governance/validations/tracking_plan 'tracking_plan' is invalid: must be of pattern #tracking-plan:<id>

Event Stream source spec syntax must be valid

syntactic error

Rule ID: event-stream/source/spec-syntax-valid

Examples

Valid legacy source spec with required fields

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: src-js-1
  name: My JavaScript Source
  type: javascript

Valid legacy source spec with Tracking Plan governance

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-node-source
spec:
  id: src-node-1
  name: My Node.js Source
  type: node
  governance:
    validations:
      tracking_plan: "#/tp/my-group/tp-main"
      config: {}

Legacy source spec missing required id

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-source
spec:
  name: My Source
  type: javascript
Diagnostics
  • spec.yaml /id 'id' is required

Legacy source spec with unsupported source type

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My Source
  type: unknown_sdk
Diagnostics
  • spec.yaml /type 'type' must be one of

Legacy source spec with invalid Tracking Plan reference format

spec.yaml yaml 
version: rudder/0.1
kind: event-stream-source
metadata:
  name: my-source
spec:
  id: src-1
  name: My Source
  type: javascript
  governance:
    validations:
      tracking_plan: "#tracking-plan:tp-1"
      config: {}
Diagnostics
  • spec.yaml /governance/validations/tracking_plan 'tracking_plan' is invalid: must be of pattern #/tp/<group>/<id>

URNs must be unique across the project

syntactic errorAll spec versions

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic errorAll spec versions

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic errorAll spec versions

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' is required
## 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 (Swift) | `ios_swift` | | Android (Kotlin) | `android_kotlin` | | iOS (Obj-C) | `ios` | | Android (Java) | `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](https://www.rudderstack.com/docs/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](https://www.rudderstack.com/docs/rudder-cli/event-stream-sources/) for feature overview, and the [Event Stream Sources walkthrough](https://www.rudderstack.com/docs/rudder-cli/event-stream-sources-walkthrough/) for step-by-step setup - See [CLI-based Tracking Plan Management](https://www.rudderstack.com/docs/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](https://www.rudderstack.com/docs/rudder-cli/yaml-data-catalog-and-tracking-plans/) for information about Tracking Plan YAML structure - See [Manage Destinations using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/destinations/) and [Connection YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-connections/) to send events from this source to a destination