2 unstable releases
new 0.2.0 | Mar 29, 2025 |
---|---|
0.1.0 | Mar 28, 2025 |
#69 in Development tools
128 downloads per month
110KB
2.5K
SLoC
ConfigGuard 🛡️
A high-performance validation tool for YAML and JSON configuration files, with a flexible schema definition system.
Features:
- ✅ Validate YAML/JSON against schema rules
- 🚀 Fast execution for CI/CD pipelines
- 📝 Detailed error reporting (text or JSON)
- 🔍 Strict mode for rejecting unknown fields
- 📂 Directory scanning support
- 🛠️ Flexible schema definition language
Overview
ConfigGuard helps catch configuration errors early in development or CI/CD pipelines, preventing runtime failures caused by invalid structures, types, or values. It emphasizes:
- Accuracy: Reliable validation according to defined schema rules
- Performance: Quick execution for CI/CD pipelines
- Usability: Simple CLI interface with detailed error messages
- Standalone: Distributed as a single binary with no external dependencies
- Flexibility: Support for complex nested structures and precise constraints
Installation
From Crates.io
cargo install configguard
From Source
git clone https://github.com/charmitro/configguard
cd configguard
cargo build --release
The binary will be located at target/release/configguard
.
Usage
Basic Validation
configguard validate config.yaml --schema schema.yaml
ConfigGuard automatically detects YAML (.yaml, .yml) and JSON (.json) configuration files based on their extension.
JSON Output Format
configguard validate config.yaml --schema schema.yaml --format json
Strict Mode (Reject Unknown Keys)
configguard validate config.yaml --schema schema.yaml --strict
Validate Multiple Files
configguard validate config1.yaml config2.yaml --schema schema.yaml
Validate All Files in a Directory
configguard validate ./configs/ --schema schema.yaml --directory
Exit Codes
ConfigGuard uses the following exit codes:
0
: Success - All configurations are valid2
: File not found3
: File read/write error4
: Parse error (invalid YAML/JSON)5
: Unsupported file format10
: Validation error(s)11
: Schema error12
: Pattern error (invalid regex)20
: CLI error
Options
--schema, -s <path>
: Path to the schema definition file (required)--format <type>
: Output format (text
(default),json
)--strict
: Enable strict validation (reject unknown fields)--directory, -d
: Process all compatible files in specified directories
Schema Definition
ConfigGuard uses a YAML-based schema definition language. Here's an example:
type: object
description: Root configuration object
keys:
apiVersion:
type: string
required: true
pattern: ^v1(alpha|beta)?\d*$
description: The API version string.
kind:
type: string
required: true
enum: [Deployment, Service, ConfigMap]
description: The type of Kubernetes resource.
metadata:
type: object
required: true
keys:
name:
type: string
required: true
min_length: 1
max_length: 63
labels:
type: object
allow_unknown_keys: true # Allow arbitrary labels
spec:
type: object
required: true
keys:
replicas:
type: integer
min: 0
description: Number of replicas.
containers:
type: list
required: true
min_length: 1
items:
type: object
keys:
name: { type: string, required: true }
image: { type: string, required: true }
See the examples/
directory for more schema examples.
Supported Types
string
: Text valuesinteger
: Whole numbersfloat
: Decimal numbersboolean
: True/false valuesobject
: Nested structures with key-value pairslist
: Ordered collections of items
Type-Specific Constraints
Common
description
: Human-readable description of the field (shown in error messages)required
: Whether the key must exist (defaults to false)
Object Type
keys
: Map of child keys and their validation rulesallow_unknown_keys
: Whether to allow keys not defined in schema (defaults to false in strict mode)
List Type
items
: Validation rules applied to each list itemmin_length
: Minimum number of itemsmax_length
: Maximum number of items
String Type
pattern
: Regular expression the string must matchenum
: List of allowed valuesmin_length
: Minimum string lengthmax_length
: Maximum string length
Numeric Types (Integer/Float)
min
: Minimum allowed value (inclusive)max
: Maximum allowed value (inclusive)enum
: List of allowed values
Error Reporting
Text Format
ConfigGuard provides detailed error messages showing exactly what's wrong with your configuration:
Error: 7 validation errors found:
1. Error at path '.apiVersion': String doesn't match pattern
Expected: Pattern: ^v1(alpha|beta)?\d*$
Found: v2
Description: The API version string.
2. Error at path '.kind': Value not in allowed set
Expected: One of: String("Deployment"), String("Service"), String("ConfigMap")
Found: Job
Description: The type of Kubernetes resource.
3. Error at path '.metadata.name': String too long
Expected: At most 63 characters
Found: 79 characters
JSON Format
For integration with other tools, use JSON output format:
{
"valid": false,
"error_count": 7,
"errors": [
{
"path": ".apiVersion",
"message": "String doesn't match pattern",
"expected": "Pattern: ^v1(alpha|beta)?\\d*$",
"actual": "v2",
"description": "The API version string."
},
{
"path": ".kind",
"message": "Value not in allowed set",
"expected": "One of: String(\"Deployment\"), String(\"Service\"), String(\"ConfigMap\")",
"actual": "Job",
"description": "The type of Kubernetes resource."
}
]
}
Examples
The examples/
directory contains sample configurations and schemas to help you get started:
simple/
: Basic examples for validating individual config filesdirectory-validation/
: Examples for validating multiple files in a directory
License
This project is licensed under the MIT License - see the LICENSE file for details.
Dependencies
~5.5–7.5MB
~140K SLoC