Rudder CLI Validation Rules Beta

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

Available Plans

free
growth
enterprise

33 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

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
      event_type: track
      name: Order Completed

b.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      event_type: track
      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
      event_type: track
      name: Order Completed

b.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      event_type: track
      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'

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
      event_type: track
      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
      event_type: track
      name: Order Completed

Diagnostics

spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' is required

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
      event_type: track
      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/0.1
kind: transformation
metadata:
  name: my-transformations
spec:
  id: my-transformation
  name: My Transformation
  language: javascript
  code: |
    export function transformEvent(event, metadata) {
      return event;
    }

Diagnostics

spec.yaml /kind kind 'transformation' is not supported with version 'rudder/0.1'

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:
    - id: my_test_property
      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:
    - id: my_test_property
      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

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 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

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 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

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
      name: Address
      type: object

spec2.yaml yaml

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

Diagnostics

spec.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'
spec2.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
      name: Address
      type: object

spec2.yaml yaml

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

Diagnostics

spec.yaml /types/0/name duplicate name 'Address' within kind 'custom-types'
spec2.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

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
      event_type: track
      name: Page Viewed

spec2.yaml yaml

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

Diagnostics

spec.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'
spec2.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
      event_type: track
      name: Page Viewed

spec2.yaml yaml

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

Diagnostics

spec.yaml /events/0 duplicate name 'Page Viewed' within kind 'events'
spec2.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 'event_type' must be one of [track screen identify group page]

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 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

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 'format' must be one of: [date-time, date, time, email, uuid, hostname, ipv4, ipv6]

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
      name: User ID
      type: string

spec2.yaml yaml

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

Diagnostics

spec.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'
spec2.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
      name: User ID
      type: string

spec2.yaml yaml

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

Diagnostics

spec.yaml /properties/0 duplicate name, type and itemTypes: 'User ID' within kind 'properties'
spec2.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

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)

The referenced event exists in the catalog, so the Tracking Plan validates cleanly.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup

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.

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup
    - id: page_view
      event_type: track
      name: Page View

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"

spec2.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'
spec2.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)

The referenced event exists in the catalog, so the Tracking Plan validates cleanly.

events.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup

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.

events.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: my-events
spec:
  events:
    - id: signup
      event_type: track
      name: Signup
    - id: page_view
      event_type: track
      name: Page View

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"

spec2.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'
spec2.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

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 relationships from event models must have cardinality 'many-to-one', got "one-to-many"

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 relationships from entity models to event models must have cardinality 'one-to-many', got "many-to-one"

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 target model "data-graph-model:non-existent" 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 a relationship from model "data-graph-model:user" to model "data-graph-model:account" already exists; at most one relationship is allowed per source-target pair
spec.yaml /models/0/relationships/1 a relationship from model "data-graph-model:user" to model "data-graph-model:account" already exists; 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 "User"
spec.yaml /models/1/display_name duplicate model display name "User"

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 "Links To"
spec.yaml /models/1/relationships/0/display_name duplicate relationship display name "Links To"

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
  display_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 tracking plan 'tp-missing' 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'
source-b.yaml /name duplicate name 'Shared Name' 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: tp
metadata:
  name: tp-main
spec:
  id: tp-main
  display_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 tracking plan 'tp-missing' 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'
source-b.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 [java dotnet php flutter cordova rust react_native python ios android javascript go node ruby unity swift kotlin]

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>

SQL Models

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

Two SQL models sharing the same display_name collide in the resource graph and fail validation.

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

spec2.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'
spec2.yaml /display_name duplicate display_name 'Churn Risk Model' within kind 'retl-source-sql-model'

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

Two SQL models sharing the same display_name collide in the resource graph and fail validation.

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

spec2.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'
spec2.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

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

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]

Transformations

Transformation imports must resolve to existing transformation libraries

semantic error

Rule ID: transformations/transformation/semantic-valid

Examples

Transformation without library imports is valid

Code that imports nothing has no library references to resolve, so the rule passes.

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  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

The code imports a library handle with no matching library resource in the project, so the import cannot be resolved.

spec.yaml yaml

version: rudder/v1
kind: transformation
metadata:
  name: my-transformations
spec:
  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:
  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:
  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:
  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:
  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:
  id: my-transformation
  name: My Transformation
  language: javascript

Diagnostics

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

Transformation libraries

Transformations

Transformation library must be semantically valid

semantic error

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

Examples

Transformation library with unique import_name

A single library whose import_name no other library claims validates cleanly.

spec.yaml yaml

version: rudder/v1
kind: transformation-library
metadata:
  name: my-libraries
spec:
  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

Two libraries declaring the same import_name collide in the resource graph and fail validation.

spec.yaml yaml

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

spec2.yaml yaml

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

Diagnostics

spec.yaml /import_name import_name 'mathUtils' is duplicate
spec2.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:
  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:
  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:
  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:
  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:
  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

URNs must be unique across the project

Examples

Distinct URNs across files

Same URN declared in two files

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

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

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

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)

Custom type references must resolve to existing resources

Examples

Unique custom type names (legacy)

Duplicate custom type names across files (legacy)

Custom type spec syntax must be valid

Examples

Valid custom-types spec

v1 custom type missing required id field

Custom type spec syntax must be valid

Examples

Valid legacy custom-types spec

Legacy custom type missing required name field

Legacy custom type missing required type field

Events

Event references must resolve to existing resources

Examples

Unique event name and type combinations (v1)

Duplicate event name and type across files (v1)

Event references must resolve to existing resources

Examples

Unique event name and type combinations (legacy)

Duplicate event name and type across files (legacy)

Event spec syntax must be valid

Examples

Valid events spec

v1 event missing required event_type field