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 error

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 error

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

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

events.yaml yaml

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

import-manifest.yaml yaml

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

Same URN imported by both a manifest and inline metadata

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

events.yaml yaml

version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed

import-manifest.yaml yaml

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

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

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

events.yaml yaml

version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed

import-manifest.yaml yaml

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

Diagnostics

import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic error

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