#yaml-config #schema-validation #schema #config #config-json #field #yaml

app configguard

A high-performance utility to validate configuration files against a user-defined schema

2 unstable releases

new 0.2.0 Mar 29, 2025
0.1.0 Mar 28, 2025

#69 in Development tools

Download history 128/week @ 2025-03-24

128 downloads per month

MIT license

110KB
2.5K SLoC

ConfigGuard 🛡️

Crates.io CI Status License: MIT

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 valid
  • 2: File not found
  • 3: File read/write error
  • 4: Parse error (invalid YAML/JSON)
  • 5: Unsupported file format
  • 10: Validation error(s)
  • 11: Schema error
  • 12: 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 values
  • integer: Whole numbers
  • float: Decimal numbers
  • boolean: True/false values
  • object: Nested structures with key-value pairs
  • list: 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 rules
  • allow_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 item
  • min_length: Minimum number of items
  • max_length: Maximum number of items

String Type

  • pattern: Regular expression the string must match
  • enum: List of allowed values
  • min_length: Minimum string length
  • max_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 files
  • directory-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