Configuration Validation

DevEx provides comprehensive validation for all configuration files, ensuring YAML syntax correctness, schema compliance, and logical consistency. Validation helps catch configuration errors early and maintains reliable development environment setups.

Validation Overview

What Gets Validated

YAML Syntax

Proper YAML formatting and structure

Schema Compliance

Required fields and data types

Logical Consistency

Dependencies, conflicts, and constraints

Platform Compatibility

Platform-specific requirements

Validation Levels

Syntax Validation: YAML parsing and basic structure
Schema Validation: Field types, required properties, constraints
Semantic Validation: Dependencies, conflicts, platform compatibility
Runtime Validation: Available installers, network resources

Configuration Schema

Application Schema

The application configuration schema defines strict validation rules:

# Schema for application definitions
application:
  type: object
  required: [name, description, category]
  properties:
    name:
      type: string
      pattern: "^[a-zA-Z0-9._-]+$"
      minLength: 1
      maxLength: 50
    description:
      type: string
      minLength: 10
      maxLength: 200
    category:
      type: string
      enum: [
        "Development", "Databases", "System Tools", 
        "Productivity", "Communication", "Multimedia"
      ]
    default:
      type: boolean
      default: false
    install_method:
      type: string
      enum: [
        "apt", "dnf", "pacman", "brew", "winget", 
        "chocolatey", "scoop", "flatpak", "snap", 
        "mise", "docker", "curlpipe"
      ]
    dependencies:
      type: array
      items:
        type: string
        pattern: "^[a-zA-Z0-9._-]+$"
    platforms:
      type: array
      items:
        type: string
        enum: ["linux", "macos", "windows"]

Environment Schema

Programming languages and environment validation:

# Programming language schema
programming_language:
  type: object
  required: [name, category, install_method, install_command]
  properties:
    name:
      type: string
      pattern: "^[a-zA-Z0-9. ]+$"
    category:
      type: string
      const: "Programming Languages"
    install_method:
      type: string
      const: "mise"
    install_command:
      type: string
      pattern: "^[a-zA-Z0-9@.:-]+$"
    dependencies:
      type: array
      items:
        type: string

# Font schema
font:
  type: object
  required: [name, method]
  properties:
    name:
      type: string
      minLength: 1
    method:
      type: string
      enum: ["url", "package", "oh-my-posh", "homebrew"]
    url:
      type: string
      format: uri
      # Required when method is "url"
    destination:
      type: string
      pattern: "^[~./].*"

Desktop Schema

Desktop environment configuration validation:

# Desktop application schema
desktop_application:
  type: object
  required: [name, description, category]
  properties:
    desktop_environments:
      type: array
      items:
        type: string
        enum: ["gnome", "kde", "xfce", "i3", "macos", "windows", "all"]
    linux:
      $ref: "#/definitions/platform_config"
    macos:
      $ref: "#/definitions/platform_config"
    windows:
      $ref: "#/definitions/platform_config"

# Platform configuration schema
platform_config:
  type: object
  required: [install_method, install_command]
  properties:
    install_method:
      type: string
    install_command:
      type: string
    official_support:
      type: boolean
      default: true
    alternatives:
      type: array
      items:
        $ref: "#/definitions/platform_config"

System Schema

System configuration validation:

# Git configuration schema
git_config:
  type: object
  properties:
    aliases:
      type: object
      patternProperties:
        "^[a-zA-Z0-9-]+$":
          type: string
    settings:
      type: object
      properties:
        pull:
          type: object
          properties:
            rebase:
              type: boolean
        push:
          type: object
          properties:
            default:
              type: string
              enum: ["simple", "current", "upstream", "matching"]

# Theme validation
global_theme:
  type: string
  enum: [
    "Tokyo Night", "Gruvbox", "Catppuccin", 
    "Dracula", "Nord", "One Dark", "Solarized"
  ]

Validation Commands

Basic Validation

# Validate all configuration files
devex config validate

# Validate with detailed output
devex config validate --verbose

# Validate and show warnings
devex config validate --warnings

# Quick validation (syntax only)
devex config validate --quick

Validation Output

DevEx provides structured validation output:

# Example validation output
$ devex config validate applications

✓ YAML Syntax: Valid
✓ Schema Compliance: Valid
✗ Dependency Check: 2 issues found
✗ Platform Compatibility: 1 issue found

Issues:
[ERROR] applications.yaml:45 - Missing dependency 'curl' for application 'docker'
[ERROR] applications.yaml:67 - Dependency cycle detected: git -> gitui -> git
[WARN]  applications.yaml:123 - Application 'xcode' not available on linux platform
[INFO]  Found 23 applications, 15 marked as default

Recommendations:
- Add 'curl' to docker dependencies
- Resolve circular dependency between git and gitui
- Consider platform-specific application definitions

Common Validation Issues

YAML Syntax Errors

# ❌ Incorrect indentation
applications:
  development:
  - name: git  # Should be indented under development
    description: "Version control"
    
# ✅ Correct indentation
applications:
  development:
    - name: git
      description: "Version control"

Schema Validation Errors

Missing Required Fields: All applications must have name, description, category

Invalid Field Types: Boolean fields cannot contain strings

Enum Violations: Category must be one of predefined values

Pattern Mismatches: Names must follow naming conventions

# ❌ Schema violations
applications:
  development:
    - name: ""  # Empty name not allowed
      # Missing required description and category
      default: "yes"  # Should be boolean, not string
      category: "Tools"  # Not in allowed enum values
      
# ✅ Schema compliant
applications:
  development:
    - name: "git"
      description: "Distributed version control system"
      category: "Development"
      default: true

Dependency Validation Issues

Common dependency problems:

# ❌ Missing dependency
applications:
  development:
    - name: docker-compose
      dependencies:
        - docker  # OK
        - python  # Not defined in configuration
        
# ✅ All dependencies defined
applications:
  development:
    - name: python
      # python definition
    - name: docker
      # docker definition  
    - name: docker-compose
      dependencies:
        - docker
        - python

Advanced Validation

Custom Validation Rules

DevEx supports custom validation rules for organization-specific requirements:

# .devex/validation-rules.yaml
custom_rules:
  - name: "require_security_tools"
    description: "All configurations must include security tools"
    rule: |
      applications.development must contain {
        name: "1password" or name: "bitwarden"
      }
    severity: "error"
    
  - name: "standardize_editor"
    description: "Limit editor choices to approved list"
    rule: |
      applications.development.name in ["vscode", "nvim", "emacs"]
      when category == "Editors"
    severity: "warning"
    
  - name: "version_pinning"
    description: "Production environments must pin versions"
    rule: |
      programming_languages.install_command must not contain "@latest"
      when environment_type == "production"
    severity: "error"

Template Validation

Template-specific validation ensures template integrity:

# Validate template structure
devex template validate web-development

# Check template variables
devex template validate --check-vars web-development

# Validate template on all platforms
devex template validate --all-platforms mobile-development

# Test template application
devex template validate --apply-test data-science

Network Validation

Validate external resources and URLs:

# Check URL accessibility
devex config validate --check-urls

# Validate repository access
devex config validate --check-repos

# Test package availability
devex config validate --check-packages

# Verify installer functionality
devex config validate --test-installers

Validation in CI/CD

Pre-commit Validation

Set up validation in Git pre-commit hooks:

# .git/hooks/pre-commit
#!/bin/bash
echo "Validating DevEx configuration..."

# Validate all configurations
if ! devex config validate --quick; then
    echo "❌ Configuration validation failed"
    echo "Run 'devex config validate' for details"
    exit 1
fi

echo "✅ Configuration validation passed"

GitHub Actions Validation

# .github/workflows/validate-config.yml
name: Validate DevEx Configuration

on:
  push:
    paths:
      - '.devex/**'
      - 'config/**'
  pull_request:
    paths:
      - '.devex/**'
      - 'config/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install DevEx
        run: |
          # Review security guide before installation
          wget -qO- https://devex.sh/install | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          
      - name: Validate Configuration
        run: |
          devex config validate --verbose
          
      - name: Check Template Validity
        run: |
          devex template validate --all
          
      - name: Test Configuration Application
        run: |
          devex install --dry-run --all

Team Validation Workflow

Local Validation: Developers validate before committing

Pre-commit Hooks: Automatic validation on commit

CI Pipeline: Validation in pull requests

Regular Audits: Periodic validation of live configurations

Fixing Validation Issues

Auto-fix Common Issues

DevEx can automatically fix some validation issues:

# Auto-fix formatting issues
devex config fix --format

# Fix missing required fields with defaults
devex config fix --add-defaults

# Sort and organize configuration
devex config fix --organize

# Fix dependency order
devex config fix --dependencies

Manual Fix Guidelines

# Check YAML syntax with detailed errors
devex config parse applications.yaml --verbose

# Use YAML linter
yamllint ~/.devex/applications.yaml

# Format YAML correctly
devex config format applications.yaml

Best Practices

Configuration Validation Best Practices:

Validate Early: Check configurations before committing
Use Pre-commit Hooks: Automatic validation in development workflow
Regular Audits: Periodic validation of live configurations
Document Custom Rules: Clear documentation for organization-specific validation
Test Templates: Validate templates on all target platforms
Monitor Dependencies: Regular checks for missing or outdated dependencies
Version Control Validation Rules: Track changes to validation requirements

Validation Workflow

# Daily development workflow
git add .devex/
devex config validate        # Local validation
git commit -m "Update config"  # Triggers pre-commit validation

# Team configuration changes
devex config validate --deep  # Comprehensive validation
devex template validate --all  # Template validation
devex config test-apply --dry-run  # Test actual application

Error Prevention

# Use descriptive names and documentation
applications:
  development:
    - name: "docker"
      description: "Container platform for application deployment"
      category: "Development"
      # Clear, specific configuration reduces validation errors
      
    # Document custom or complex configurations
    - name: "custom-tool"
      description: "Company-specific development tool"
      # NOTE: This tool requires VPN access
      install_method: "curlpipe"
      install_command: "internal.company.com/tools/install.sh"

Troubleshooting Validation

# Debug validation with maximum verbosity
devex config validate --debug --verbose

# Check specific validation rule
devex config validate --rule dependency_check

# Skip problematic validations temporarily
devex config validate --skip-network-checks

# Validate with specific schema version
devex config validate --schema-version 2.0.0

Configuration Index - Overview of all configurations
Applications Configuration - Application validation specifics
Template System - Template validation
CLI Reference: Config - Configuration management commands

Configuration validation ensures reliable, consistent development environments by catching errors early and enforcing best practices. Regular validation prevents configuration drift and maintains team standards.

Configuration Validation

Configuration ValidationCopy Anchor Link

Validation OverviewCopy Anchor Link

What Gets ValidatedCopy Anchor Link

YAML Syntax

Schema Compliance

Logical Consistency

Platform Compatibility

Validation LevelsCopy Anchor Link

Configuration SchemaCopy Anchor Link

Application SchemaCopy Anchor Link

Environment SchemaCopy Anchor Link

Desktop SchemaCopy Anchor Link

System SchemaCopy Anchor Link

Validation CommandsCopy Anchor Link

Basic ValidationCopy Anchor Link

Validation OutputCopy Anchor Link

Common Validation IssuesCopy Anchor Link

YAML Syntax ErrorsCopy Anchor Link

Schema Validation ErrorsCopy Anchor Link

Dependency Validation IssuesCopy Anchor Link

Advanced ValidationCopy Anchor Link

Custom Validation RulesCopy Anchor Link

Template ValidationCopy Anchor Link

Network ValidationCopy Anchor Link

Validation in CI/CDCopy Anchor Link

Pre-commit ValidationCopy Anchor Link

GitHub Actions ValidationCopy Anchor Link

Team Validation WorkflowCopy Anchor Link

Fixing Validation IssuesCopy Anchor Link

Auto-fix Common IssuesCopy Anchor Link

Manual Fix GuidelinesCopy Anchor Link

Best PracticesCopy Anchor Link

Validation WorkflowCopy Anchor Link

Error PreventionCopy Anchor Link

Troubleshooting ValidationCopy Anchor Link

Related DocumentationCopy Anchor Link

On this page

Configuration Validation

Validation Overview

What Gets Validated

Validation Levels

Configuration Schema

Application Schema

Environment Schema

Desktop Schema

System Schema

Validation Commands

Basic Validation

Validation Output

Common Validation Issues

YAML Syntax Errors

Schema Validation Errors

Dependency Validation Issues

Advanced Validation

Custom Validation Rules

Template Validation

Network Validation

Validation in CI/CD

Pre-commit Validation

GitHub Actions Validation

Team Validation Workflow

Fixing Validation Issues

Auto-fix Common Issues

Manual Fix Guidelines

Best Practices

Validation Workflow

Error Prevention

Troubleshooting Validation

Related Documentation