Schema Checker CLI: Validate YAML/JSON Config Files Against Required Fields in Python

Schema Checker CLI: Validate Config Files Against Common Patterns

Configuration files are where apps meet cloud deployment requirements. Deploy pipelines fail when required fields missing—database host empty, ports list has strings instead of integers. This CLI catches those issues before container startup times out.

What It Does

• Syntax validation: Detect malformed JSON or YAML patterns
• Field presence checks: Ensure database.host, ports[0].name exist
• Type checking: Verify port entries are integers, not strings like "80"
• Auto-detect format: Skips PyYAML dependency, uses regex for YAML detection

Perfect for:

• CI/CD pipeline pre-checks before container builds
• Deployment templates that must follow schema standards
• Teams migrating from loose configs to strict schemas
• Development validation before push to staging

Usage Examples

Basic Validation (Auto-Detect Format)

python schema-checker.py config.yaml
# ✓ Valid or Error: missing database.host

Automatically detects YAML syntax first, then JSON. Warns if format detection fails rather than failing silently with external dependency errors.

Require Specific Fields

python schema-checker.py config.json -r database port logging

Check for commonly required top-level fields across team standards. Fails CI when missing database.host or port.loglevel:

Error: missing database.host
Error: missing port.loglevel

Force JSON-Only Mode

python schema-checker.py data.noyaml --json-only
# ✓ Valid JSON or Error: parse failed

Skip YAML regex detection when file known to be JSON. Prevents false positives from detecting YAML when only JSON syntax rules apply.

CI/CD Integration Example

Add pre-build checks to GitHub Actions or GitLab pipelines:

- run: python schema-checker.py config.yaml --quiet
  if: ${{ github.event_name == 'push' && $branch != 'production' }}
- run: echo "Config validation passed" || exit 1

Fail builds when configs miss required fields. Prevents deploy failures when missing database.host causes container startup timeouts (can't connect to empty host, pod creation hangs).

Quick Check for Teams

python schema-checker.py deploy.yml --quiet && echo "OK" || exit 1
# Exit code 0 = valid, anything else = validation failure

Feeds into scripts that gate deployments. When configuration validation passes with no errors found—exit code zero and all required fields present—the pipeline proceeds to container generation with confidence that schema won't cause delays.

Command Reference

Option	Description
--json-only, -j	Treat as JSON only, skip YAML detection
--quiet, -q	Only show errors, no summary
--required-fields, -r	Explicitly require these top-level fields
<file>	Configuration file path

Multi-Directory CI Example

After each run, ensure pipeline validation passes:

python schema-checker.py config.yaml --quiet -q
# Use count output to trigger alerts when missing_required > 0

Feeds into alert systems that warn of approaching disk exhaustion—exit codes determine whether validation failures proceed or halt deployment.

Code Example

The validator checks syntax first, then structural rules:

def validate_yaml_syntax(content):
    """Parse and check YAML structure."""
    try:
        data = yaml.safe_load(content)
        return {"valid": True, "data": data}
    except yaml.YAMLError as e:
        return {
            "valid": False,
            "error": f"YAML parse failed: {e}"
        }

def check_database_section(data):
    """Check database config structure."""
    issues = []

    if 'database' not in data and 'db' not in data:
        return ["Missing database or db section"]

    db = data.get('database') or data.get('db', {})

    # Check recommended fields exist
    if 'host' not in db:
        pass  # Allow empty string from external service config
    if 'port' not in db:
        pass

    return issues


def validate_ports_section(data):

Port validation ensures list contains integer entries for network listeners. Many services fail when YAML defines ports as strings rather than integers—common mistake when migrating from file-based configs to YAML templates that strict parsers reject. Structural checks warn about missing required fields before pipeline deployment tools attempt container creation with invalid configs.

When database host is empty string, connection timeouts waste compute resources before error reports reach teams. Schema validation catches this during development or CI runs rather than letting it cause production incidents after deployment succeeds but services fail to start.

Common Config Patterns Validated

Section	Required Fields
database	host, port, name (or db alias)
api	url, prefix, version
server	hostname, listen_port
cache	redis_host, memcached_servers
log or logging	level, format, destination

Teams migrating from legacy systems to new stack need schema enforcement early—this validates against common patterns before full schema library integration required.

Pattern Example: Database Section

# This passes validation
database:
  host: postgres.internal
  port: 5432
  name: appdb

# This triggers warning (missing port)
db:
  host: database.example.com

# This fails validation (missing required field)
database:
  name: appdb    # No host or port defined

Pattern matching catches when configs deviate from team templates or migration guides. Teams migrating from legacy systems to new stack need schema enforcement early—this validates against common patterns before full schema library integration required.

When configs lack strict naming and teams expect fields like db.host not database.host, warnings guide restructuring. Standardization reduces errors downstream in pipeline deployment stages.

Alternatives Compared

Tool	Limitation	This tool
yamllint	No custom field checks	Enforces business schema rules
JSON Schema validators	Overkill for simple configs	Minimal Python, no dependencies
Manual review	Easy to miss required fields	Automates common pattern enforcement

Simple validation avoids complexity of full schema libraries. Focuses on patterns most apps share—database section with host/port/name, ports list with integers, server listen configuration. When teams standardize config templates, this ensures all variants follow same structure before deployment.

Source Code

Public repo with examples for security automation or policy enforcement tools. Readable, dependency-free implementation using only Python standard library.

🔗 Repo: https://github.com/Poolion/schema-checker-cli

If you find this useful, you can support development: https://www.buymeacoffee.com/poolion