Journey YAML Validation

tdx journey validate                      # Validate all journey YAML files locally
tdx journey validate path/to/journey.yml  # Validate specific file
tdx journey push --dry-run                # Preview changes before push

Validation Checks

Structure Validation

Step Count Validation

Step Validation

Flow Control Validation

API Constraints (not checked by tdx journey validate, but rejected by the API)

Schema Validation (Zod)

Reference Validation

Required Structure

type: journey              # Required
name: Journey Name
reentry: no_reentry        # no_reentry | reentry_unless_goal_achieved | reentry_always

goal:                      # Recommended (warning if missing)
  name: Goal Name
  segment: goal-segment    # Embedded segment (defined in segments: section)

journeys:
  - state: draft
    stages:
      - name: Stage Name
        entry_criteria:        # Required
          name: Entry Name
          segment: entry-segment
        exit_criteria:         # Recommended (warning if missing)
          - name: Exit Name
            segment: exit-segment
        milestone:             # Required for non-last stages
          name: Milestone Name
          segment: milestone-segment
        steps:                 # At least 2 steps required (4+ recommended)
          - type: activation
            name: Send Email
            next: End Stage
            with:
              activation: email-key
          - type: end
            name: End Stage

Limits: Max 8 stages (validated locally). API constraints: 120 events/journey, 70 events/stage, 30 versions

Step Types Quick Reference

Important: next: is a direct field on step, not inside with:. The value must be the exact step name as written (e.g., Send Email), not a slugified version (e.g., send-email).

Design Rules (not caught by validator)

• Condition wait paths MUST lead to different actions — if both paths do the same thing, use duration wait instead
• Every branch (decisionpoint, abtest, condition wait) should perform a meaningful, distinct action
• Prefer flat branching over nested branching — inner branches must merge before joining outer branch
• A wait step must follow every activation step (place after merge if activation → merge)
• Frequency capping: wait between activations; avoid >1 message/day/channel
• Consent/Suppression: use entrycriteria/exitcriteria segments for opt-in and removal

Flow Control Rules

# Pattern: decision → actions → merge → wait → end
- type: decision_point
  name: Check Status
  with:
    branches:
      - name: Active
        segment: active_users
        next: Send Offer          # Must NOT point directly to merge
      - name: Others
        excluded: true
        next: Send Reminder

- type: activation
  name: Send Offer
  next: Rejoin
  with: { activation: offer }

- type: activation
  name: Send Reminder
  next: Rejoin
  with: { activation: reminder }

- type: merge
  name: Rejoin                    # Required: multiple paths need merge
  next: Wait After Rejoin         # Must NOT point to another merge

- type: wait
  name: Wait After Rejoin
  next: end
  with: { duration: 1, unit: day }

- type: end
  name: End Stage

Condition Wait Format

Condition wait has NO top-level next: — paths are inside condition:

with:
  condition:
    segment: made-purchase
    next: matched-path          # Path when condition met
    timeout:
      duration: 14
      unit: day
      next: timeout-path        # Path when max wait exceeded

See journey skill for all wait step options (duration, waituntil, daysof_week).

Segment References

• Embedded (recommended): segment: my-segment (defined in segments: section)
• External ref: segment: ref:Segment Name — see journey skill for ref: limitations

Related Skills

• journey - Full journey creation and management
• validate-segment - Segment rule validation