2026-01-14 03:09:18 +00:00
|
|
|
# Configuration Validation Guide\n\n## Overview\n\nThe new configuration system includes comprehensive schema validation to catch errors early and ensure configuration correctness.\n\n## Schema Validation Features\n\n### 1. Required Fields Validation\n\nEnsures all required fields are present:\n\n```\n# Schema definition\n[required]\nfields = ["name", "version", "enabled"]\n\n# Valid config\nname = "my-service"\nversion = "1.0.0"\nenabled = true\n\n# Invalid - missing 'enabled'\nname = "my-service"\nversion = "1.0.0"\n# Error: Required field missing: enabled\n```\n\n### 2. Type Validation\n\nValidates field types:\n\n```\n# Schema\n[fields.port]\ntype = "int"\n\n[fields.name]\ntype = "string"\n\n[fields.enabled]\ntype = "bool"\n\n# Valid\nport = 8080\nname = "orchestrator"\nenabled = true\n\n# Invalid - wrong type\nport = "8080" # Error: Expected int, got string\n```\n\n### 3. Enum Validation\n\nRestricts values to predefined set:\n\n```\n# Schema\n[fields.environment]\ntype = "string"\nenum = ["dev", "staging", "prod"]\n\n# Valid\nenvironment = "prod"\n\n# Invalid\nenvironment = "production" # Error: Must be one of: dev, staging, prod\n```\n\n### 4. Range Validation\n\nValidates numeric ranges:\n\n```\n# Schema\n[fields.port]\ntype = "int"\nmin = 1024\nmax = 65535\n\n# Valid\nport = 8080\n\n# Invalid - below minimum\nport = 80 # Error: Must be >= 1024\n\n# Invalid - above maximum\nport = 70000 # Error: Must be <= 65535\n```\n\n### 5. Pattern Validation\n\nValidates string patterns using regex:\n\n```\n# Schema\n[fields.email]\ntype = "string"\npattern = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"\n\n# Valid\nemail = "admin@example.com"\n\n# Invalid\nemail = "not-an-email" # Error: Does not match pattern\n```\n\n### 6. Deprecated Fields\n\nWarns about deprecated configuration:\n\n```\n# Schema\n[deprecated]\nfields = ["old_field"]\n\n[deprecated_replacements]\nold_field = "new_field"\n\n# Config using deprecated field\nold_field = "value" # Warning: old_field is deprecated. Use new_field instead.\n```\n\n## Using Schema Validator\n\n### Command Line\n\n```\n# Validate workspace config\nprovisioning workspace config validate\n\n# Validate provider config\nprovisioning provider validate aws\n\n# Validate platform service config\nprovisioning platform validate orchestrator\n\n# Validate with detailed output\nprovisioning workspace config validate --verbose\n```\n\n### Programmatic Usage\n\n```\nuse provisioning/core/nulib/lib_provisioning/config/schema_validator.nu *\n\n# Load config\nlet config = (open ~/workspaces/my-project/config/provisioning.yaml | from yaml)\n\n# Validate against schema\nlet result = (validate-workspace-config $config)\n\n# Check results\nif $result.valid {\n print "✅ Configuration is valid"\n} else {\n print "❌ Configuration has errors:"\n for error in $result.errors {\n print $" • ($error.message)"\n }\n}\n\n# Display warnings\nif ($result.warnings | length) > 0 {\n print "⚠️ Warnings:"\n for warning in $result.warnings {\n print $" • ($warning.message)"\n }\n}\n```\n\n### Pretty Print Results\n\n```\n# Validate and print formatted results\nlet result = (validate-workspace-config $config)\nprint-validation-results $result\n```\n\n## Schema Examples\n\n### Workspace Schema\n\nFile: `/Users/Akasha/project-provisioning/provisioning/config/workspace.schema.toml`\n\n```\n[required]\nfields = ["workspace", "paths"]\n\n[fields.workspace]\ntype = "record"\n\n[fields.workspace.name]\ntype = "string"\npattern = "^[a-z][a-z0-9-]*$"\n\n[fields.workspace.version]\ntype = "string"\npattern = "^\\d+\\.\\d+\\.\\d+$"\n\n[fields.paths]\ntype = "record"\n\n[fields.paths.base]\ntype = "string"\n\n[fields.paths.infra]\ntype = "string"\n\n[fields.debug]\ntype = "record"\n\n[fields.debug.enabled]\ntype = "bool"\n\n[fields.debug.log_level]\ntype = "string"\nenum = ["debug", "info", "warn", "error"]\n```\n\n### Provider Schema (AWS)\n\nFile: `/Users/Akasha/project-provisioning/provisioning/extensions/providers/aws/config.schema.toml`\n\n```\n[required]\nfields = ["provider", "crede
|
