Rudder CLI Validation Rules Beta

Interactive reference for all Rudder CLI validation rules with valid and invalid example specs.

Available Plans

free
growth
enterprise

86 minute read

Every spec you apply with the Rudder CLI is checked against the rules in this guide before it reaches your workspace.

Each rule includes valid and invalid example specs and the diagnostics you see when validation fails.

How to use this guide
Use the Spec version toggle to switch between rudder/v1 and legacy rudder/0.1 spec.
Filter by phase or search to narrow the list.

Project

Resource kind must be supported with the specified version

syntactic errorAll spec versions

Rule ID: project/resource-kind-version-valid

Examples

Kind declared with a supported version

The events kind supports rudder/v1, so this spec is accepted. The rule flags kind/version pairs where the kind is recognized but the version is not registered.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: order_completed
      name: Order Completed

Known kind declared with an unsupported version

The transformation kind is recognized but registered only for rudder/v1, not rudder/0.1. The rule reports the unsupported kind/version pair.

spec.yaml yaml

version: rudder/v0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: order_completed
      name: Order Completed

Diagnostics

spec.yaml /kind is not supported with version

Spec syntax must be valid

syntactic errorAll spec versions

Rule ID: project/spec-syntax-valid

Examples

Spec with all required top-level fields

A well-formed spec with version, kind, metadata, and spec — the four required top-level fields.

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - name: MyTestProperty
      type: string

Spec missing required kind

Every spec must declare a kind.

spec.yaml yaml

version: rudder/v1
kind:
metadata:
  name: my-properties
spec:
  properties:
    - name: MyTestProperty
      type: string

Diagnostics

spec.yaml /kind 'kind' is required

Spec missing required version

Every spec must declare a version.

spec.yaml yaml

version:
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - name: MyTestProperty
      type: string

Diagnostics

spec.yaml /version 'version' is required

Spec missing required metadata block

Every spec must declare a metadata block.

spec.yaml yaml

version: rudder/v1
kind: properties
spec:
  properties:
    - name: MyTestProperty
      type: string

Diagnostics

spec.yaml /metadata 'metadata' is required

Spec missing required spec body

Every spec must declare a spec body.

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties

Diagnostics

spec.yaml /spec 'spec' is required

Import manifest

Project

A (workspace_id, urn) must not be defined more than once across import-manifest files

syntactic error

Rule ID: import-manifest/duplicate-urn

Examples

Distinct URNs across manifest files

Two manifest files declaring different URNs in the same workspace. No collision, so the project is valid.

a.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:source-a"
          remote_id: "remote_a"

b.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:source-b"
          remote_id: "remote_b"

Same URN under different workspaces across files

The same urn maps to a different remote per workspace. Because the uniqueness key is (workspace_id, urn), this is allowed.

a.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:shared"
          remote_id: "remote_ws1"

b.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-2"
      resources:
        - urn: "event-stream-source:shared"
          remote_id: "remote_ws2"

Same (workspace, urn) in two manifest files

Both files map the same urn under the same workspace. The rule flags every occurrence across the colliding files.

a.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:my-source"
          remote_id: "remote_a"

b.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:my-source"
          remote_id: "remote_b"

Diagnostics

a.yaml /spec/workspaces/0/resources/0/urn duplicate URN 'event-stream-source:my-source' in workspace 'ws-1'
b.yaml /spec/workspaces/0/resources/0/urn duplicate URN 'event-stream-source:my-source' in workspace 'ws-1'

Same (workspace, urn) twice in one manifest file

A urn repeated under one workspace in a single file is a collision too. The rule flags every occurrence.

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:my-source"
          remote_id: "remote_1"
        - urn: "event-stream-source:my-source"
          remote_id: "remote_2"

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn duplicate URN 'event-stream-source:my-source' in workspace 'ws-1'
import-manifest.yaml /spec/workspaces/0/resources/1/urn duplicate URN 'event-stream-source:my-source' in workspace 'ws-1'

Every import-manifest URN must match a resource defined in the project

semantic error

Rule ID: import-manifest/orphaned-urn

Examples

Manifest URN matches a resource in the project

The manifest imports event:order_completed, and an events spec defines a resource resolving to that URN, so the entry is not orphaned.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events
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"

Manifest URN with no matching resource in the project

The manifest imports event:order_completed, but no spec defines a resource with that URN — a stale entry or a typo. The rule flags it for the active workspace.

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 manifest URN 'event:order_completed' does not match any resource in the project

Import-manifest spec syntax must be valid

syntactic error

Rule ID: import-manifest/spec-syntax-valid

Examples

Well-formed import manifest

A manifest with one workspace and urn-based resources. Every resource carries a urn and a remote_id, so the manifest is valid.

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event-stream-source:my-source"
          remote_id: "src_remote_456"

Workspace missing workspace_id

Each workspace block must declare a workspace_id.

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - resources:
        - urn: "event-stream-source:my-source"
          remote_id: "src_remote_456"

Diagnostics

import-manifest.yaml /spec/workspaces/0/workspace_id workspace_id is required

Resource using local_id instead of urn

Manifests require urn; local_id is rejected because manifests are a forward-looking format.

import-manifest.yaml yaml

version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - local_id: "my-source"
          remote_id: "src_remote_456"

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn urn is required in manifests (local_id not supported)

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

Custom types

Data Catalog

Custom type config must be valid for the given type

syntactic error

Rule ID: datacatalog/custom-types/config-valid

Examples

Valid string config with pattern

spec.yaml yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_status
      name: UserStatus
      type: string
      config:
        enum: ["active", "inactive"]

v1 string config with invalid format

spec.yaml yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_email
      name: UserEmail
      type: string
      config:
        format: not_a_valid_format

Diagnostics

spec.yaml /types/0/config/format not_a_valid_format

Custom type config must be valid for the given type

syntactic error

Rule ID: datacatalog/custom-types/config-valid

Examples

Valid string config with enum (legacy)

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_status
      name: UserStatus
      type: string
      config:
        enum: ["active", "inactive"]
        pattern: "^[a-z]+$"

Valid integer config with range (legacy)

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: age
      name: Age
      type: integer
      config:
        minimum: 0
        maximum: 120

String config with invalid format (legacy)

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_email
      name: UserEmail
      type: string
      config:
        format: invalid_format

Diagnostics

spec.yaml /types/0/config/format invalid_format

Custom type references must resolve to existing resources

semantic error

Rule ID: datacatalog/custom-types/semantic-valid

Examples

Unique custom type names (v1)

spec.yaml yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object
    - id: user_status
      name: UserStatus
      type: string

Duplicate custom type names across files (v1)

Duplicate custom type names in the resource graph fail validation.

spec.yaml yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address_v2
      name: Address
      type: object

Diagnostics

spec.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'

Custom type references must resolve to existing resources

semantic error

Rule ID: datacatalog/custom-types/semantic-valid

Examples

Unique custom type names (legacy)

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object
    - id: user_status
      name: UserStatus
      type: string

Duplicate custom type names across files (legacy)

Duplicate custom type names in the resource graph fail validation.

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address_v2
      name: Address
      type: object

Diagnostics

spec.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'

Custom type spec syntax must be valid

syntactic error

Rule ID: datacatalog/custom-types/spec-syntax-valid

Examples

Valid custom-types spec

spec.yaml yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      type: object
    - id: user_status
      name: UserStatus
      type: string

v1 custom type missing required id field

spec.yaml yaml

version: rudder/v1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - name: UserStatus
      type: string

Diagnostics

spec.yaml /types/0/id 'id' is required

Custom type spec syntax must be valid

syntactic error

Rule ID: datacatalog/custom-types/spec-syntax-valid

Examples

Valid legacy custom-types spec

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address
      description: Physical address structure
      type: object
    - id: user_status
      name: UserStatus
      type: string

Legacy custom type missing required name field

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: user_status
      type: string

Diagnostics

spec.yaml /types/0/name 'name' is required

Legacy custom type missing required type field

spec.yaml yaml

version: rudder/0.1
kind: custom-types
metadata:
  name: my-custom-types
spec:
  types:
    - id: address
      name: Address

Diagnostics

spec.yaml /types/0/type 'type' is required

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

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

Events

Data Catalog

Event references must resolve to existing resources

semantic error

Rule ID: datacatalog/events/semantic-valid

Examples

Unique event name and type combinations (v1)

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
    - id: product_clicked
      event_type: track
      name: Product Clicked

Duplicate event name and type across files (v1)

Duplicate event name and event_type pairs in the resource graph fail validation.

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed_2
      event_type: track
      name: Page Viewed

Diagnostics

spec.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'

Event references must resolve to existing resources

semantic error

Rule ID: datacatalog/events/semantic-valid

Examples

Unique event name and type combinations (legacy)

spec.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
    - id: product_clicked
      event_type: track
      name: Product Clicked

Duplicate event name and type across files (legacy)

Duplicate event name and event_type pairs in the resource graph fail validation.

spec.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed_2
      event_type: track
      name: Page Viewed

Diagnostics

spec.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'

Event spec syntax must be valid

syntactic error

Rule ID: datacatalog/events/spec-syntax-valid

Examples

Valid events spec

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
    - id: user_identified
      event_type: identify

v1 event missing required event_type field

spec.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      name: Page Viewed

Diagnostics

spec.yaml /events/0/event_type 'event_type' is required

Event spec syntax must be valid

syntactic error

Rule ID: datacatalog/events/spec-syntax-valid

Examples

Valid legacy events spec

spec.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: page_viewed
      event_type: track
      name: Page Viewed
      description: User viewed a page
    - id: user_identified
      event_type: identify

Legacy event missing required id field

spec.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - name: Page Viewed
      event_type: track

Diagnostics

spec.yaml /events/0/id 'id' is required

Legacy event with invalid event_type

spec.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: my_event
      event_type: custom

Diagnostics

spec.yaml /events/0/event_type oneof

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

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

Properties

Data Catalog

Property config must be valid for the given type

syntactic error

Rule ID: datacatalog/properties/config-valid

Examples

Valid string property config

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      config:
        format: "email"
        min_length: 5

v1 string property config with invalid format

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      config:
        format: totally_wrong

Diagnostics

spec.yaml /properties/0/propConfig/format totally_wrong

Property config must be valid for the given type

syntactic error

Rule ID: datacatalog/properties/config-valid

Examples

Valid string property config with format (legacy)

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      propConfig:
        format: "email"
        minLength: 5
        maxLength: 100

Valid integer property config with range (legacy)

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: age
      name: Age
      type: integer
      propConfig:
        minimum: 0
        maximum: 120

String property config with invalid format (legacy)

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_email
      name: User Email
      type: string
      propConfig:
        format: not_valid

Diagnostics

spec.yaml /properties/0/propConfig/format not_valid

Property references must resolve to existing resources

semantic error

Rule ID: datacatalog/properties/semantic-valid

Examples

Unique property name and type combinations (v1)

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string
    - id: email
      name: Email
      type: string

Duplicate property name, type, and itemTypes across files (v1)

Duplicate property name, type, and itemTypes in the resource graph fail validation.

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id_2
      name: User ID
      type: string

Diagnostics

spec.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'

Property references must resolve to existing resources

semantic error

Rule ID: datacatalog/properties/semantic-valid

Examples

Unique property name and type combinations (legacy)

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string
    - id: email
      name: Email
      type: string

Duplicate property name, type, and itemTypes across files (legacy)

Duplicate property name, type, and itemTypes in the resource graph fail validation.

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id_2
      name: User ID
      type: string

Diagnostics

spec.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'

Property spec syntax must be valid

syntactic error

Rule ID: datacatalog/properties/spec-syntax-valid

Examples

Valid properties spec

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      type: string
    - id: age
      name: Age
      type: integer

v1 property missing required id field

spec.yaml yaml

version: rudder/v1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - name: User ID
      type: string

Diagnostics

spec.yaml /properties/0/id 'id' is required

Property spec syntax must be valid

syntactic error

Rule ID: datacatalog/properties/spec-syntax-valid

Examples

Valid legacy properties spec

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      name: User ID
      description: Unique identifier for the user
      type: string
    - id: email
      name: Email
      type: string

Legacy property missing required id field

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - name: User ID
      type: string

Diagnostics

spec.yaml /properties/0/id 'id' is required

Legacy property missing required name field

spec.yaml yaml

version: rudder/0.1
kind: properties
metadata:
  name: my-properties
spec:
  properties:
    - id: user_id
      type: string

Diagnostics

spec.yaml /properties/0/name 'name' is required

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

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

Tracking Plans

Tracking Plan references must resolve to existing resources

semantic error

Rule ID: datacatalog/tracking-plans/semantic-valid

Examples

Tracking Plan with unique display_name (v1)

spec.yaml yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event: "#event:signup"

Duplicate Tracking Plan display_name across files (v1)

Duplicate Tracking Plan display_name values in the resource graph fail validation.

spec.yaml yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan-2
spec:
  id: my_tp_2
  display_name: My Tracking Plan
  rules:
    - id: page_rule
      type: event_rule
      event: "#event:page_view"

Diagnostics

spec.yaml /display_name duplicate display_name 'My Tracking Plan' within kind 'tracking-plan'

Tracking Plan references must resolve to existing resources

semantic error

Rule ID: datacatalog/tracking-plans/semantic-valid

Examples

Tracking Plan with unique display_name (legacy)

spec.yaml yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/signup"

Duplicate Tracking Plan display_name across files (legacy)

Duplicate Tracking Plan display_name values in the resource graph fail validation.

spec.yaml yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan-2
spec:
  id: my_tp_2
  display_name: My Tracking Plan
  rules:
    - id: page_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/page_view"

Diagnostics

spec.yaml /display_name duplicate display_name 'My Tracking Plan' within kind 'tp'

Tracking Plan spec syntax must be valid

syntactic error

Rule ID: datacatalog/tracking-plans/spec-syntax-valid

Examples

Valid Tracking Plan spec

spec.yaml yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event: "#event:signup"
      properties:
        - property: "#property:user_id"
          required: true

Tracking Plan rule missing event field

spec.yaml yaml

version: rudder/v1
kind: tracking-plan
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: no_event_rule
      type: event_rule
      properties:
        - property: "#property:user_id"
          required: true

Diagnostics

spec.yaml /rules/0/event 'event' is required

Tracking Plan spec syntax must be valid

syntactic error

Rule ID: datacatalog/tracking-plans/spec-syntax-valid

Examples

Valid legacy Tracking Plan spec

spec.yaml yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: signup_rule
      type: event_rule
      event:
        $ref: "#/events/user-events/signup"
      properties:
        - $ref: "#/properties/common/user_id"
          required: true

Legacy Tracking Plan rule missing event field

spec.yaml yaml

version: rudder/0.1
kind: tp
metadata:
  name: my-tracking-plan
spec:
  id: my_tp
  display_name: My Tracking Plan
  rules:
    - id: no_event_rule
      type: event_rule
      properties:
        - $ref: "#/properties/common/user_id"
          required: true

Diagnostics

spec.yaml /rules/0/event 'event' is required

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

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

Data Graph

Relationship cardinality must be valid for the source and target model types

semantic error

Rule ID: datagraph/data-graph/relationship-cardinality-valid

Examples

Entity-to-entity relationship with any cardinality is valid

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account
          display_name: User Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id

Event-to-entity relationship uses many-to-one cardinality

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-user
          display_name: Purchase User
          cardinality: many-to-one
          target: "#data-graph-model:user"
          source_join_key: user_id
          target_join_key: user_id
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id

Event models cannot connect to other event models

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-click
          display_name: Purchase Click
          cardinality: many-to-one
          target: "#data-graph-model:click"
          source_join_key: session_id
          target_join_key: session_id
    - id: click
      display_name: Click
      type: event
      table: db.schema.clicks
      timestamp: clicked_at

Diagnostics

spec.yaml /models/0/relationships/0/cardinality event models cannot be connected to other event models

Event-to-entity relationship requires many-to-one cardinality

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-user
          display_name: Purchase User
          cardinality: one-to-many
          target: "#data-graph-model:user"
          source_join_key: user_id
          target_join_key: user_id
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id

Diagnostics

spec.yaml /models/0/relationships/0/cardinality must have cardinality 'many-to-one'

Entity-to-event relationship requires one-to-many cardinality

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-purchase
          display_name: User Purchase
          cardinality: many-to-one
          target: "#data-graph-model:purchase"
          source_join_key: user_id
          target_join_key: user_id
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at

Diagnostics

spec.yaml /models/0/relationships/0/cardinality must have cardinality 'one-to-many'

Relationship target references must resolve to existing models

semantic error

Rule ID: datagraph/data-graph/relationship-refs-valid

Examples

Relationship target references an existing model in the Data Graph

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account
          display_name: User Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id

Relationship target references a missing model

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-missing
          display_name: User Missing
          cardinality: one-to-one
          target: "#data-graph-model:non-existent"
          source_join_key: ref_id
          target_join_key: ref_id

Diagnostics

spec.yaml /models/0/relationships/0/target does not exist

At most one relationship is allowed per source-target model pair

semantic error

Rule ID: datagraph/data-graph/relationship-unique-pair

Examples

Multiple relationships from one model to different targets are allowed

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account
          display_name: User Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
        - id: user-profile
          display_name: User Profile
          cardinality: one-to-one
          target: "#data-graph-model:profile"
          source_join_key: profile_id
          target_join_key: profile_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id
    - id: profile
      display_name: Profile
      type: entity
      table: db.schema.profiles
      primary_id: profile_id

A-to-B and B-to-A relationships are distinct and both allowed

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-to-account
          display_name: User to Account
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id
      relationships:
        - id: account-to-user
          display_name: Account to User
          cardinality: one-to-one
          target: "#data-graph-model:user"
          source_join_key: account_id
          target_join_key: account_id

Duplicate source-target model pairs are not allowed

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-account-v1
          display_name: User Account v1
          cardinality: one-to-one
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: account_id
        - id: user-account-v2
          display_name: User Account v2
          cardinality: one-to-many
          target: "#data-graph-model:account"
          source_join_key: account_id
          target_join_key: id
    - id: account
      display_name: Account
      type: entity
      table: db.schema.accounts
      primary_id: account_id

Diagnostics

spec.yaml /models/0/relationships/0 at most one relationship is allowed per source-target pair
spec.yaml /models/0/relationships/1 at most one relationship is allowed per source-target pair

Data Graph spec syntax must be valid

syntactic error

Rule ID: datagraph/data-graph/spec-syntax-valid

Examples

Valid Data Graph spec with entity and event models

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      root: true
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases
      timestamp: purchased_at
      relationships:
        - id: purchase-user
          display_name: Purchase User
          cardinality: many-to-one
          target: "#data-graph-model:user"
          source_join_key: user_id
          target_join_key: user_id

Data Graph missing required account_id

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph

Diagnostics

spec.yaml /account_id 'account_id' is required

Entity model missing required primary_id

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users

Diagnostics

spec.yaml /models/0/primary_id 'primary_id' is required for entity models

Event model missing required timestamp

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: purchase
      display_name: Purchase
      type: event
      table: db.schema.purchases

Diagnostics

spec.yaml /models/0/timestamp 'timestamp' is required for event models

Model table must use catalog.schema.table format

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: schema.users
      primary_id: user_id

Diagnostics

spec.yaml /models/0/table 'table' must be a 3-part reference in the format catalog.schema.table

Model and relationship names must be unique within a Data Graph

semantic error

Rule ID: datagraph/data-graph/unique-names-valid

Examples

Unique model and relationship display names within the Data Graph

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-order
          display_name: User Order
          cardinality: one-to-many
          target: "#data-graph-model:order"
          source_join_key: user_id
          target_join_key: user_id
    - id: order
      display_name: Order
      type: entity
      table: db.schema.orders
      primary_id: order_id

Duplicate model display names within a Data Graph

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
    - id: user-v2
      display_name: User
      type: entity
      table: db.schema.users_v2
      primary_id: user_id

Diagnostics

spec.yaml /models/0/display_name duplicate model display name
spec.yaml /models/1/display_name duplicate model display name

Duplicate relationship display names within a Data Graph

spec.yaml yaml

version: rudder/v1
kind: data-graph
metadata:
  name: my-data-graph
spec:
  id: my-data-graph
  account_id: wh-account-123
  models:
    - id: user
      display_name: User
      type: entity
      table: db.schema.users
      primary_id: user_id
      relationships:
        - id: user-order
          display_name: Links To
          cardinality: one-to-many
          target: "#data-graph-model:order"
          source_join_key: user_id
          target_join_key: user_id
    - id: order
      display_name: Order
      type: entity
      table: db.schema.orders
      primary_id: order_id
      relationships:
        - id: order-product
          display_name: Links To
          cardinality: one-to-many
          target: "#data-graph-model:product"
          source_join_key: order_id
          target_join_key: order_id
    - id: product
      display_name: Product
      type: entity
      table: db.schema.products
      primary_id: product_id

Diagnostics

spec.yaml /models/0/relationships/0/display_name duplicate relationship display name
spec.yaml /models/1/relationships/0/display_name duplicate relationship display name

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

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

Sources

Event Stream

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

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

Connections

Event Stream

An enabled Event Stream connection needs both its endpoints enabled to deliver events

semantic warning

Rule ID: event-stream/connection/enabled-endpoints-valid

Examples

Enabled connection whose source and destination are both enabled

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
      enabled: true

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: true

Disabled connection may point at disabled endpoints

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
      enabled: false

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: false
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: false

Enabled connection whose source is disabled

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: false

Diagnostics

connections.yaml /spec/connections/0/source connection 'js-to-s3' is enabled but its source 'my-js-source' is disabled

Enabled connection whose destination is disabled

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: false
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: true

Diagnostics

connections.yaml /spec/connections/0/destination connection 'js-to-s3' is enabled but its destination 'my-s3-destination' is disabled

Event Stream connection endpoints must exist in the project and form a valid, compatible topology

semantic error

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

Examples

Connection whose source and destination exist and are compatible

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript

Connection whose source does not exist in the project

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: ghost-to-s3
      source: "#event-stream-source:ghost-source"
      destination: "#destination:my-s3-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

Diagnostics

connections.yaml /spec/connections/0/source event stream source 'ghost-source' not found in the project

Connection whose destination does not exist in the project

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-ghost
      source: "#event-stream-source:my-js-source"
      destination: "#destination:ghost-destination"

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript

Diagnostics

connections.yaml /spec/connections/0/destination destination 'ghost-destination' not found in the project

The same source-destination pair connected twice

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
    - id: js-to-s3-again
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript

Diagnostics

connections.yaml /spec/connections/0 connected more than once in the project
connections.yaml /spec/connections/1 connected more than once in the project

Destination that does not support the source's type

The WEBHOOK definition here supports web and android sources only; a python source connects as a cloud source, so the pairing is rejected.

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: python-to-webhook
      source: "#event-stream-source:my-python-source"
      destination: "#destination:my-webhook-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-webhook-destination
spec:
  id: my-webhook-destination
  display_name: Production Webhook
  type: WEBHOOK
  enabled: true
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook"

source.yaml yaml

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

Diagnostics

connections.yaml /spec/connections/0/destination does not support source 'my-python-source'

Destination declaring no settings for the source's type

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      android: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript

Diagnostics

connections.yaml /spec/connections/0/destination has no 'connection_mode' entry for source type 'web'

Destination config missing a field the source type requires to connect

The WEBHOOK definition here requires webhook_url before a web source may connect in cloud mode; the config declares that mode but omits the field.

connections.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-webhook
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-webhook-destination"

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: my-webhook-destination
spec:
  id: my-webhook-destination
  display_name: Production Webhook
  type: WEBHOOK
  enabled: true
  definition_version: 1
  config:
    connection_mode:
      web: cloud

source.yaml yaml

version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript

Diagnostics

connections.yaml /spec/connections/0/destination config is missing fields required to connect a 'web' source

Event Stream connection spec syntax must be valid

syntactic error

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

Examples

Valid connection linking an Event Stream source to a destination

spec.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
      source: "#event-stream-source:my-android-source"
      destination: "#destination:my-s3-destination"

Valid connection list with an explicitly disabled entry

spec.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
      source: "#event-stream-source:my-android-source"
      destination: "#destination:my-s3-destination"
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
      enabled: false

Connection entry missing required source and destination

spec.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3

Diagnostics

spec.yaml /spec/connections/0/source 'source' is required
spec.yaml /spec/connections/0/destination 'destination' is required

Connection whose source is not a reference

spec.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
      source: "my-android-source"
      destination: "#destination:my-s3-destination"

Diagnostics

spec.yaml /spec/connections/0/source 'source' is invalid: must be of pattern #event-stream-source:<id>

Connection whose source ref points at a rETL source kind

spec.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: model-to-s3
      source: "#retl-source-sql-model:my-model"
      destination: "#destination:my-s3-destination"

Diagnostics

spec.yaml /spec/connections/0/source 'source' must reference an event stream source (#event-stream-source:<id>), got a 'retl-source-sql-model' reference

Connection whose destination ref points at a source

spec.yaml yaml

version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
      source: "#event-stream-source:my-android-source"
      destination: "#event-stream-source:my-js-source"

Diagnostics

spec.yaml /spec/connections/0/destination 'destination' must reference a destination (#destination:<id>), got a 'event-stream-source' reference

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

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

Destinations

Destination transformation reference must resolve to a project transformation and display_name must be unique across destinations

semantic error

Rule ID: destination/semantic-valid

Examples

Destination whose transformation exists in the project

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  transformation: "#transformation:my-transformation"
  config:
    webhook_url: "https://example.com/hook"

transformation.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformation
spec:
  id: my-transformation
  name: My Transformation
  language: javascript
  code: "export function transformEvent(event) { return event; }"

Destination references a transformation that does not exist in the project

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  transformation: "#transformation:ghost"
  config:
    webhook_url: "https://example.com/hook"

Diagnostics

destination.yaml /transformation not found in the project

Two destinations share the same display_name

destination-a.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-a
spec:
  id: webhook-a
  display_name: Shared Name
  type: WEBHOOK
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook-a"

destination-b.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-b
spec:
  id: webhook-b
  display_name: Shared Name
  type: WEBHOOK
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook-b"

Diagnostics

destination-a.yaml /display_name duplicate display_name
destination-b.yaml /display_name duplicate display_name

Destination spec envelope, registered type/version, transformation reference format and config must be valid

syntactic error

Rule ID: destination/spec-syntax-valid

Examples

Valid destination with registered type, version and config

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  enabled: true
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook"

Unknown envelope field is rejected

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  unexpected_field: true
  config:
    webhook_url: "https://example.com/hook"

Diagnostics

destination.yaml /unexpected_field unknown field

Destination type not present in the definition registry

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: mystery-dest
spec:
  id: mystery-dest
  display_name: Mystery Destination
  type: NOT_A_REAL_TYPE
  definition_version: 1
  config: {}

Diagnostics

destination.yaml /type is not supported

Transformation reference must match #transformation:<id>

destination.yaml yaml

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  transformation: "transformation/my-transformation"
  config:
    webhook_url: "https://example.com/hook"

Diagnostics

destination.yaml /transformation must be of pattern #transformation:<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

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

SQL Models

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

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

RETL SQL model semantic constraints must be satisfied

semantic error

Rule ID: retl/sqlmodel/semantic-valid

Examples

Valid SQL model with unique display_name

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: churn-model
spec:
  id: churn-model
  display_name: Churn Risk Model
  account_id: acc-456
  primary_key: user_id
  source_definition: bigquery
  sql: SELECT user_id FROM churn_signals

v1 SQL model with duplicate display_name

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: churn-model-duplicate
spec:
  id: churn-model-duplicate
  display_name: Churn Risk Model
  account_id: acc-456
  primary_key: user_id
  source_definition: bigquery
  sql: SELECT user_id FROM churn_signals

Diagnostics

spec.yaml /display_name duplicate display_name 'Churn Risk Model' within kind 'retl-source-sql-model'

V1 SQL models whose display_names differ only in case (names compare case-insensitively)

churn-lowercase.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: churn-model-lowercase
spec:
  id: churn-model-lowercase
  display_name: churn risk model
  account_id: acc-456
  primary_key: user_id
  source_definition: bigquery
  sql: SELECT user_id FROM churn_signals

churn.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: churn-model
spec:
  id: churn-model
  display_name: Churn Risk Model
  account_id: acc-456
  primary_key: user_id
  source_definition: bigquery
  sql: SELECT user_id FROM churn_signals

Diagnostics

churn.yaml /display_name duplicate display_name 'Churn Risk Model' (case-insensitive match with 'churn risk model') within kind 'retl-source-sql-model'
churn-lowercase.yaml /display_name duplicate display_name 'churn risk model' (case-insensitive match with 'Churn Risk Model') within kind 'retl-source-sql-model'

V1 SQL model referencing an account that cannot back its source_definition

account.yaml yaml

version: rudder/v1
kind: account
metadata:
  name: prod-pg
spec:
  id: prod-pg
  name: Production Postgres
  account_definition_name: SOURCE_POSTGRES
  config:
    host: db.internal
    dbname: analytics
    user: rudder
    port: "5432"
    password: "{{ .PG_PASSWORD }}"

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: churn-model
spec:
  id: churn-model
  display_name: Churn Risk Model
  account: "#account:prod-pg"
  primary_key: user_id
  source_definition: snowflake
  sql: SELECT user_id FROM churn_signals

Diagnostics

spec.yaml /account account 'prod-pg' is a 'postgres' account (SOURCE_POSTGRES) and cannot back source_definition 'snowflake'

RETL SQL model semantic constraints must be satisfied

semantic error

Rule ID: retl/sqlmodel/semantic-valid

Examples

Valid legacy SQL model with unique display_name

spec.yaml yaml

version: rudder/0.1
kind: retl-source-sql-model
metadata:
  name: revenue-model
spec:
  id: revenue-model
  display_name: Revenue Model
  account_id: acc-123
  primary_key: id
  source_definition: postgres
  sql: SELECT id, amount FROM revenue

Legacy SQL model with duplicate display_name

spec.yaml yaml

version: rudder/0.1
kind: retl-source-sql-model
metadata:
  name: revenue-model-copy
spec:
  id: revenue-model-copy
  display_name: Revenue Model
  account_id: acc-123
  primary_key: id
  source_definition: postgres
  sql: SELECT id, amount FROM revenue

Diagnostics

spec.yaml /display_name duplicate display_name 'Revenue Model' within kind 'retl-source-sql-model'

RETL SQL model spec syntax must be valid

syntactic error

Rule ID: retl/sqlmodel/spec-syntax-valid

Examples

Valid SQL model spec with inline SQL

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  account_id: acc-123
  primary_key: id
  source_definition: snowflake
  sql: SELECT id, name FROM orders

Valid v1 SQL model spec referencing an account in the project instead of an account_id

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  account: "#account:prod-snowflake"
  primary_key: id
  source_definition: snowflake
  sql: SELECT id, name FROM orders

v1 SQL model missing required account_id

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  primary_key: id
  source_definition: bigquery
  sql: SELECT id, name FROM orders

Diagnostics

spec.yaml /account_id 'account_id' is required when 'account' is not specified

V1 SQL model specifying both account_id and account (mutually exclusive)

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  account_id: acc-123
  account: "#account:prod-snowflake"
  primary_key: id
  source_definition: snowflake
  sql: SELECT id, name FROM orders

Diagnostics

spec.yaml /account_id 'account_id' and 'account' cannot be specified together

v1 SQL model specifies both sql and file

spec.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  account_id: acc-123
  primary_key: id
  source_definition: postgres
  sql: SELECT id FROM orders
  file: ./query.sql

Diagnostics

spec.yaml /sql 'sql' and 'file' cannot be specified together

RETL SQL model spec syntax must be valid

syntactic error

Rule ID: retl/sqlmodel/spec-syntax-valid

Examples

Valid legacy SQL model spec with inline SQL

spec.yaml yaml

version: rudder/0.1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  account_id: acc-123
  primary_key: id
  source_definition: postgres
  sql: SELECT id, name FROM orders

Legacy SQL model missing required display_name

spec.yaml yaml

version: rudder/0.1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  account_id: acc-123
  primary_key: id
  source_definition: postgres
  sql: SELECT id, name FROM orders

Diagnostics

spec.yaml /display_name 'display_name' is required

Legacy SQL model with unsupported source_definition

spec.yaml yaml

version: rudder/0.1
kind: retl-source-sql-model
metadata:
  name: user-orders-model
spec:
  id: user-orders-model
  display_name: User Orders
  account_id: acc-123
  primary_key: id
  source_definition: oracle
  sql: SELECT id FROM orders

Diagnostics

spec.yaml /source_definition 'source_definition' must be one of [postgres redshift snowflake bigquery mysql databricks trino]

Table sources

Table Sources

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

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

RETL table source semantic constraints must be satisfied

semantic error

Rule ID: retl/table/semantic-valid

Examples

Valid table source referencing a project account of its source_definition

account.yaml yaml

version: rudder/v1
kind: account
metadata:
  name: prod-pg
spec:
  id: prod-pg
  name: Production Postgres
  account_definition_name: SOURCE_POSTGRES
  config:
    host: db.internal
    dbname: analytics
    user: rudder
    port: "5432"
    password: "{{ .PG_PASSWORD }}"

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account: "#account:prod-pg"
  source_definition: postgres
  primary_key: id
  schema: public
  table: users

S3 table source referencing an account that cannot back its source_definition

account.yaml yaml

version: rudder/v1
kind: account
metadata:
  name: prod-pg
spec:
  id: prod-pg
  name: Production Postgres
  account_definition_name: SOURCE_POSTGRES
  config:
    host: db.internal
    dbname: analytics
    user: rudder
    port: "5432"
    password: "{{ .PG_PASSWORD }}"

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: events-bucket
spec:
  id: events-bucket
  display_name: Events
  account: "#account:prod-pg"
  source_definition: s3
  bucket_name: events
  object_prefix: daily/

Diagnostics

spec.yaml /account account 'prod-pg' is a 'postgres' account (SOURCE_POSTGRES) and cannot back source_definition 's3'

Table source whose display_name differs only in case from a SQL model's (names compare case-insensitively across RETL sources)

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: users
  account_id: acc-123
  source_definition: postgres
  primary_key: id
  schema: public
  table: users

users-model.yaml yaml

version: rudder/v1
kind: retl-source-sql-model
metadata:
  name: users-model
spec:
  id: users-model
  display_name: Users
  account_id: acc-123
  primary_key: id
  source_definition: postgres
  sql: SELECT id, email FROM users

Diagnostics

spec.yaml /display_name duplicate display_name 'users' (case-insensitive match with 'Users') across RETL sources

RETL table source spec syntax must be valid (experimental kind)

syntactic error

Rule ID: retl/table/spec-syntax-valid

Examples

Valid warehouse table source

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account_id: acc-123
  source_definition: postgres
  primary_key: id
  schema: public
  table: users

Valid s3 table source

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: events-bucket
spec:
  id: events-bucket
  display_name: Events
  account_id: acc-s3
  source_definition: s3
  bucket_name: events
  object_prefix: daily/

Valid warehouse table source referencing an account in the project instead of an account_id

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account: "#account:prod-pg"
  source_definition: postgres
  primary_key: id
  schema: public
  table: users

S3 table source without the object prefix rudder-api requires

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: events-bucket
spec:
  id: events-bucket
  display_name: Events
  account_id: acc-s3
  source_definition: s3
  bucket_name: events

Diagnostics

spec.yaml /object_prefix 'object_prefix' is required when 'source_definition' is s3

Table source with neither account_id nor an account reference

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  source_definition: postgres
  primary_key: id
  schema: public
  table: users

Diagnostics

spec.yaml /account_id 'account_id' is required when 'account' is not specified

Table source specifying both account_id and account (mutually exclusive)

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account_id: acc-123
  account: "#account:prod-pg"
  source_definition: postgres
  primary_key: id
  schema: public
  table: users

Diagnostics

spec.yaml /account_id 'account_id' and 'account' cannot be specified together

Warehouse table source missing the table it reads

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account_id: acc-123
  source_definition: postgres
  primary_key: id
  schema: public

Diagnostics

spec.yaml /table 'table' is required unless 'source_definition' is s3

S3 table source declaring a primary key the s3 config cannot carry

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: events-bucket
spec:
  id: events-bucket
  display_name: Events
  account_id: acc-s3
  source_definition: s3
  primary_key: id
  bucket_name: events
  object_prefix: daily/

Diagnostics

spec.yaml /primary_key 'primary_key' is not allowed when 'source_definition' is s3

Table source with an unsupported source_definition

spec.yaml yaml

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account_id: acc-123
  source_definition: oracle
  primary_key: id
  schema: public
  table: users

Diagnostics

spec.yaml /source_definition 'source_definition' must be one of [postgres redshift snowflake bigquery mysql databricks trino s3]

Transformations

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

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

Transformation imports must resolve to existing transformation libraries

semantic error

Rule ID: transformations/transformation/semantic-valid

Examples

Transformation without library imports is valid

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - id: my-transformation
      name: My Transformation
      language: javascript
      code: |
        export function transformEvent(event, metadata) {
          event.properties.processed = true;
          return event;
        }

Transformation imports a missing library

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - id: my-transformation
      name: My Transformation
      language: javascript
      code: |
        import mathUtils from 'mathUtils';
        export function transformEvent(event, metadata) {
          event.properties.value = mathUtils.round(event.properties.value);
          return event;
        }

Diagnostics

spec.yaml /code 'mathUtils' imported library not found

Transformation spec syntax must be valid

syntactic error

Rule ID: transformations/transformation/spec-syntax-valid

Examples

Valid transformation spec with inline JavaScript

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - id: my-transformation
      name: My Transformation
      description: Enriches events with additional metadata
      language: javascript
      code: |
        export function transformEvent(event, metadata) {
          event.properties.enriched = true;
          return event;
        }

Transformation spec missing required id

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - name: My Transformation
      language: javascript
      code: |
        export function transformEvent(event, metadata) {
          return event;
        }

Diagnostics

spec.yaml /id 'id' is required

Transformation spec missing the required language

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - id: my-transformation
      name: My Transformation
      code: |
        export function transformEvent(event, metadata) {
          return event;
        }

Diagnostics

spec.yaml /language 'language' is required

Transformation spec defined with an unsupported language

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - id: my-transformation
      name: My Transformation
      language: ruby
      code: |
        def transform_event(event, metadata)
          event
        end

Diagnostics

spec.yaml /language 'language' must be one of [javascript python]

Transformation spec missing code and file

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  transformations:
    - id: my-transformation
      name: My Transformation
      language: javascript

Diagnostics

spec.yaml /code 'code' is required when 'file' is not specified

Transformation libraries

Transformations

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

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

Transformation library must be semantically valid

semantic error

Rule ID: transformations/transformation-library/semantic-valid

Examples

Transformation library with unique import_name

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - id: math-utils
      name: Math Utils
      import_name: mathUtils
      language: javascript
      code: |
        export function round(value) {
          return Math.round(value);
        }

Duplicate transformation library import_name

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - id: math-utils
      name: Math Utils
      import_name: mathUtils
      language: javascript
      code: |
        export function round(value) {
          return Math.round(value);
        }        
    - id: math-helpers
      name: Math Helpers
      import_name: mathUtils
      language: javascript
      code: |
        export function ceil(value) {
          return Math.ceil(value);
        }

Diagnostics

spec.yaml /import_name import_name 'mathUtils' is duplicate

Transformation library spec syntax must be valid

syntactic error

Rule ID: transformations/transformation-library/spec-syntax-valid

Examples

Valid transformation library spec with inline JavaScript

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - id: math-utils
      name: Math Utils
      import_name: mathUtils
      description: Utility functions for math operations
      language: javascript
      code: |
        export function round(value) {
          return Math.round(value);
        }

Transformation library spec missing required id

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - name: Math Utils
      import_name: mathUtils
      language: javascript
      code: |
        export function round(value) {
          return Math.round(value);
        }

Diagnostics

spec.yaml /id 'id' is required

Transformation library spec missing required import_name

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - id: math-utils
      name: Math Utils
      language: javascript
      code: |
        export function round(value) {
          return Math.round(value);
        }

Diagnostics

spec.yaml /import_name 'import_name' is required

Transformation library import_name is not camelCase of name

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - id: math-utils
      name: Math Utils
      import_name: MathUtils
      language: javascript
      code: |
        export function round(value) {
          return Math.round(value);
        }

Diagnostics

spec.yaml /import_name 'import_name' must be camelCase of 'name'

Transformation library spec with unsupported language

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  libraries:
    - id: math-utils
      name: Math Utils
      import_name: mathUtils
      language: ruby
      code: |
        def round(value)
          value.round
        end

Diagnostics

spec.yaml /language 'language' must be one of [javascript python]

Rudder CLI Validation Rules Beta

Project

Resource kind must be supported with the specified version

Examples

Kind declared with a supported version

Known kind declared with an unsupported version

Spec syntax must be valid

Examples

Spec with all required top-level fields

Spec missing required kind

Spec missing required version

Spec missing required metadata block

Spec missing required spec body

Import manifest

A (workspace_id, urn) must not be defined more than once across import-manifest files

Examples

Distinct URNs across manifest files

Same URN under different workspaces across files

Same (workspace, urn) in two manifest files

Same (workspace, urn) twice in one manifest file

Every import-manifest URN must match a resource defined in the project

Examples

Manifest URN matches a resource in the project

Manifest URN with no matching resource in the project

Import-manifest spec syntax must be valid

Examples

Well-formed import manifest

Workspace missing workspace_id

Resource using local_id instead of urn

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

Examples

Manifest and inline metadata import distinct resources

Same URN imported by both a manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

Categories

Category names must be unique across the Data Catalog

Examples

Unique category names (v1)

Duplicate category names across files (v1)

Category names must be unique across the Data Catalog

Examples

Unique category names (legacy)

Duplicate category names across files (legacy)

Category spec syntax must be valid

Examples

Valid categories spec

Category missing required name field

Category spec syntax must be valid

Examples

Valid legacy categories spec

Legacy category missing required name field

URNs must be unique across the project

Examples

Distinct URNs across files

Same URN declared in two files

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

Examples

Manifest and inline metadata import distinct resources

Same URN imported by both a manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

Metadata syntax must be valid

Examples

Metadata with only the required name

Metadata with a well-formed import block

Metadata missing required name

Import workspace missing required workspace_id

Custom types

Custom type config must be valid for the given type

Examples

Valid string config with pattern

v1 string config with invalid format

Custom type config must be valid for the given type

Examples

Valid string config with enum (legacy)

Valid integer config with range (legacy)

String config with invalid format (legacy)

Custom type references must resolve to existing resources

Examples

Unique custom type names (v1)

Duplicate custom type names across files (v1)