201 lines
4.3 KiB
Markdown
201 lines
4.3 KiB
Markdown
# EnvSchema
|
|
|
|
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema/actions)
|
|
[](https://pypi.org/project/envschema/)
|
|
[](https://pypi.org/project/envschema/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
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
|
|
|
|
```bash
|
|
pip install envschema
|
|
```
|
|
|
|
Or install from source:
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
envschema validate .env.schema.json --file .env
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
### validate
|
|
|
|
Validate environment variables against a schema:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
envschema check SCHEMA
|
|
```
|
|
|
|
## Schema Format
|
|
|
|
### JSON Schema
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
export DATABASE_URL="postgres://localhost/mydb"
|
|
export DEBUG_MODE="true"
|
|
envschema validate schema.json
|
|
```
|
|
|
|
### Validate with .env file
|
|
|
|
```bash
|
|
envschema validate schema.json --file .env
|
|
```
|
|
|
|
### CI/CD Integration
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
envschema generate schema.json
|
|
# Generates .env.example
|
|
|
|
envschema generate schema.json --output .env.dev
|
|
```
|
|
|
|
## API Reference
|
|
|
|
```python
|
|
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. |