EnvSchema

A CLI tool that validates environment variables against a JSON/YAML schema file. Developers define expected env vars with types, defaults, required flags, and descriptions in a schema. The tool validates actual .env files or runtime environment against this schema, catching type mismatches, missing required vars, and providing helpful error messages.

Features

• Schema validation with type checking (str, int, bool, list)
• Missing required variable detection
• .env.example generation from schema
• CI/CD integration for pre-deployment checks
• Support for JSON and YAML schema formats
• Pattern validation with regex support

Installation

pip install envschema

Or install from source:

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema.git
cd envschema
pip install -e .

Quick Start

1. Create a schema file (.env.schema.json or .env.schema.yaml):

{
  "version": "1.0",
  "envVars": [
    {
      "name": "DATABASE_URL",
      "type": "str",
      "required": true,
      "description": "PostgreSQL connection string"
    },
    {
      "name": "DEBUG_MODE",
      "type": "bool",
      "required": false,
      "default": "false"
    }
  ]
}

2. Validate your .env file:

envschema validate .env.schema.json --file .env

CLI Commands

validate

Validate environment variables against a schema:

envschema validate SCHEMA [--file PATH] [--env/--no-env] [--format text|json] [--ci] [--strict]

Options:

• SCHEMA: Path to the schema file (JSON or YAML)
• --file, -f: Path to .env file to validate
• --env/--no-env: Include os.environ in validation (default: true)
• --format, -o: Output format (text or json, default: text)
• --ci: CI mode (cleaner output)
• --strict: Fail on warnings

generate

Generate .env.example from a schema:

envschema generate SCHEMA [--output PATH] [--no-comments]

Options:

• SCHEMA: Path to the schema file
• --output, -o: Output file path (default: .env.example)
• --no-comments: Don't include description comments

check

Validate a schema file:

envschema check SCHEMA

Schema Format

JSON Schema

{
  "version": "1.0",
  "envVars": [
    {
      "name": "VAR_NAME",
      "type": "str|int|bool|list",
      "required": true|false,
      "default": "default_value",
      "description": "Variable description",
      "pattern": "regex_pattern"
    }
  ]
}

YAML Schema

version: "1.0"
envVars:
  - name: VAR_NAME
    type: str
    required: true
    default: "value"
    description: Variable description
    pattern: "^[A-Z]+$"

Supported Types

• str: String (always valid)
• int: Integer (validates numeric values)
• bool: Boolean (true, false, 1, 0, yes, no, on, off)
• list: Comma-separated list of values

Examples

Validate with environment variables

export DATABASE_URL="postgres://localhost/mydb"
export DEBUG_MODE="true"
envschema validate schema.json

Validate with .env file

envschema validate schema.json --file .env

CI/CD Integration

envschema validate schema.json --file .env --ci --format json

Exit codes:

• 0: Validation passed
• 1: Validation failed
• 2: Error (schema not found, invalid format)

Generate .env.example

envschema generate schema.json
# Generates .env.example

envschema generate schema.json --output .env.dev

API Reference

from envschema import Schema, ValidationEngine, EnvLoader

# Load schema
schema = Schema.load("schema.json")

# Load environment
loader = EnvLoader(".env")
env_vars = loader.load()

# Validate
engine = ValidationEngine(schema)
result = engine.validate(env_vars)

if not result.is_valid:
    print(result.missing_required)
    print(result.type_errors)

License

MIT License - see LICENSE file for details.