CX Schema CLI

The CX Schema CLI (cx-validate) is a command-line tool for validating CXTMS YAML module and workflow files against JSON Schema definitions. It provides detailed error feedback with examples and schema references to help fix validation issues.

Installation

npm install @cxtms/cx-schema

Quick Start

# Validate a module file
npx cx-validate modules/my-module.yaml

# Validate a workflow file
npx cx-validate workflows/my-workflow.yaml

# Validate multiple files
npx cx-validate modules/*.yaml workflows/*.yaml

Commands

validate (default)

Validate YAML file(s) against JSON Schema definitions.

cx-validate [files...]
cx-validate validate [files...]

Examples:

# Validate a single file
cx-validate modules/orders-module.yaml

# Validate all modules
cx-validate modules/*.yaml

# Validate with verbose output
cx-validate --verbose modules/orders-module.yaml

schema

Display the JSON Schema definition for a component, field, action, or task.

cx-validate schema <name>

Examples:

# Show schema for form component
cx-validate schema form

# Show schema for dataGrid component
cx-validate schema dataGrid

# Show schema for workflow
cx-validate schema workflow

# Show schema for foreach task
cx-validate schema foreach

example

Show example YAML for a component or task.

cx-validate example <name>

Examples:

# Show example for form component
cx-validate example form

# Show example for workflow
cx-validate example workflow

list

List all available schemas for validation.

cx-validate list
cx-validate list --type module
cx-validate list --type workflow

help

Display help information.

cx-validate help
cx-validate --help
cx-validate schema --help

Options

Option	Short	Description
`--help`	`-h`	Show help message
`--version`	`-v`	Show version number
`--type <type>`	`-t`	Validation type: `module`, `workflow`, or `auto` (default: `auto`)
`--format <format>`	`-f`	Output format: `pretty`, `json`, or `compact` (default: `pretty`)
`--schemas <path>`	`-s`	Path to custom schemas directory
`--verbose`		Show detailed output with schema paths
`--quiet`	`-q`	Only show errors, suppress other output

Output Formats

Pretty (default)

Human-readable output with colored formatting, detailed error information, and suggestions.

cx-validate modules/my-module.yaml

╔═══════════════════════════════════════════════════════════════════╗
║                  CX SCHEMA VALIDATION REPORT                     ║
╚═══════════════════════════════════════════════════════════════════╝

  File:    modules/my-module.yaml
  Type:    module
  Status:  ✓ PASSED
  Errors:  0
  Warnings:0

Compact

Minimal output showing only pass/fail and error count. Ideal for batch processing.

cx-validate --format compact modules/*.yaml

PASS modules/orders-module.yaml
PASS modules/contacts-module.yaml
FAIL modules/broken-module.yaml (3 errors)

JSON

JSON output suitable for CI/CD pipelines and programmatic processing.

cx-validate --format json modules/my-module.yaml > results.json

{
  "isValid": true,
  "errors": [],
  "warnings": [],
  "summary": {
    "file": "modules/my-module.yaml",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "status": "PASSED",
    "errorCount": 0,
    "warningCount": 0,
    "errorsByType": {}
  }
}

Validation Types

Module Validation

Validates CXTMS UI module definitions including:

Module metadata (name, appModuleId, displayName)
Components (form, dataGrid, layout, tabs, etc.)
Routes and navigation
Entities and permissions
Actions (navigate, mutation, query, etc.)
Fields (text, number, select, date, etc.)

cx-validate --type module modules/my-module.yaml

Workflow Validation

Validates CXTMS workflow definitions including:

Workflow metadata (workflowId, name, executionMode)
Activities and steps
Tasks (Query/GraphQL, Order/Create, foreach, switch, etc.)
Inputs, outputs, and variables
Triggers and schedules
Conditions and expressions

cx-validate --type workflow workflows/my-workflow.yaml

Auto-Detection

By default, the CLI auto-detects the file type based on content:

Files with workflow: property are validated as workflows
Files with module: or components: property are validated as modules

cx-validate my-file.yaml  # Auto-detects type

Available Schemas

Module Schemas

Components:

layout - Layout container
form - Form component
dataGrid - Data grid/table
tabs, tab - Tab containers
field - Form fields
button - Button component
collection - Collection display
dropdown - Dropdown menu
datasource - Data source configuration
calendar - Calendar component
card - Card component
navbar - Navigation bar
timeline - Timeline display

Fields:

text, textarea - Text inputs
number - Numeric input
select, select-async - Selection fields
date, datetime, time - Date/time fields
checkbox, radio - Boolean inputs
attachment - File attachments
autocomplete-googleplaces - Address autocomplete

Actions:

navigate, navigateBack - Navigation
mutation - GraphQL mutations
query - GraphQL queries
notification - User notifications
dialog - Modal dialogs
workflow - Workflow execution
setFields, setStore - State management
validateForm - Form validation

Workflow Schemas

Core:

workflow - Main workflow definition
activity - Activity container
input, output - I/O definitions
variable - Variable definitions
trigger - Workflow triggers
schedule - Scheduled execution

Control Flow Tasks:

foreach - Loop over collections
switch - Conditional branching
while - Conditional loops
validation - Data validation

Utility Tasks:

map - Data transformation
setVariable - Variable assignment
httpRequest - HTTP requests
log - Logging
error - Error handling
csv - CSV operations
export - Data export
template - Template rendering

Entity Tasks:

order - Order operations
contact - Contact operations
commodity - Commodity operations
job - Job operations
attachment - Attachment operations
charge - Charge operations
payment - Payment operations

Communication Tasks:

email-send - Send emails
document-render - Render documents
document-send - Send documents

Query Tasks:

graphql - GraphQL queries (Query/GraphQL, Query/GraphQL@1)

Error Types

Error Type	Description
`yaml_syntax_error`	Invalid YAML syntax
`missing_property`	Required property missing
`schema_violation`	Value doesn't match schema
`invalid_component`	Invalid component structure
`invalid_activity`	Invalid workflow activity
`invalid_task_type`	Unknown task type
`deprecated_property`	Using deprecated property (warning)

Exit Codes

Code	Description
`0`	Validation passed (no errors)
`1`	Validation failed (errors found)
`2`	CLI error (invalid arguments, file not found, etc.)

Environment Variables

Variable	Description
`CX_SCHEMA_PATH`	Default path to schemas directory
`NO_COLOR`	Disable colored output

CI/CD Integration

GitHub Actions

- name: Validate YAML files
  run: |
    npx cx-validate --format compact modules/*.yaml workflows/*.yaml

GitLab CI

validate:
  script:
    - npx cx-validate --format json modules/*.yaml > validation-results.json
  artifacts:
    paths:
      - validation-results.json

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Validate all staged YAML files
staged_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yaml|yml)$')

if [ -n "$staged_files" ]; then
  npx cx-validate --format compact $staged_files
  if [ $? -ne 0 ]; then
    echo "Validation failed. Please fix errors before committing."
    exit 1
  fi
fi

Troubleshooting

Common Issues

Schema not found

Error: Could not find schemas directory.

Solution: Run npm install or specify --schemas <path>.

YAML syntax error

YAML syntax error: duplicated mapping key (line:column)

Solution: Check for duplicate property names in your YAML file.

Type mismatch

must be equal to one of the allowed values

Solution: Use cx-validate schema <name> to see allowed values.

Getting Help

# Show general help
cx-validate --help

# Show schema for specific component
cx-validate schema <component-name>

# List all available schemas
cx-validate list

App Modules - Module development guide
Workflows - Workflow development guide

Installation​

Quick Start​

Commands​

validate (default)​

schema​

example​

list​

help​

Options​

Output Formats​

Pretty (default)​

Compact​

JSON​

Validation Types​

Module Validation​

Workflow Validation​

Auto-Detection​

Available Schemas​

Module Schemas​

Workflow Schemas​

Error Types​

Exit Codes​

Environment Variables​

CI/CD Integration​

GitHub Actions​

GitLab CI​

Pre-commit Hook​

Troubleshooting​

Common Issues​

Getting Help​

Related Documentation​

Installation

Quick Start

Commands

validate (default)

schema

example

list

help

Options

Output Formats

Pretty (default)

Compact

JSON

Validation Types

Module Validation

Workflow Validation

Auto-Detection

Available Schemas

Module Schemas

Workflow Schemas

Error Types

Exit Codes

Environment Variables

CI/CD Integration

GitHub Actions

GitLab CI

Pre-commit Hook

Troubleshooting

Common Issues

Getting Help

Related Documentation