validate-config

name

validate-config

description

Validate a config file (JSON, YAML, TOML, or .env) against a JSON Schema using config-validator. Use when you need to check that a config file is valid before deploying, catch missing required fields or wrong types, or run validation in a CI pipeline. Triggers include "validate config", "check config file", "schema validation", "validate yaml", "validate json config", "config has errors", or any task involving checking whether a config file matches its expected schema.

validate-config

Check a config file against a JSON Schema and get structured error reports.

When to use

• Before deploying, validate that all required fields are present and typed correctly
• In a CI pipeline step to block deploys on invalid configs
• When debugging why an application fails to start (check for config errors)
• After editing a config file to confirm it is still valid

Validate via CLI

# Validate against a schema stored on the server
cv validate app.config.yaml --schema my-app-config

# Validate with a local schema file
cv validate app.config.yaml --schema-file ./schemas/app.json

# Get JSON output (for scripting)
cv validate app.config.yaml --schema my-app-config --format json

# Specify server explicitly
cv validate app.config.yaml --schema my-app-config --server http://localhost:3000

Exit code 0 on pass, exit code 1 on failure or error.

Validate via API

# File upload (multipart)
curl -s -X POST http://localhost:3000/api/validate \
  -F "file=@app.config.yaml" \
  -F "schema_id=my-app-config"

# JSON body
curl -s -X POST http://localhost:3000/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "port: 8080\nhost: localhost",
    "format": "yaml",
    "schema_id": "my-app-config"
  }'

Validation result shape

{
  "valid": false,
  "errorCount": 2,
  "filename": "app.config.yaml",
  "format": "yaml",
  "durationMs": 5,
  "errors": [
    {
      "path": "/database/port",
      "message": "must be number",
      "keyword": "type",
      "lineHint": 12,
      "params": { "type": "number" }
    }
  ]
}

Supported file formats

Format	Extensions	Notes
JSON	.json	Strict JSON, no comments
YAML	.yaml .yml	YAML 1.2 safe load
TOML	.toml	TOML v1.0
env	.env	KEY=VALUE pairs, ignores comments

Format is auto-detected from file extension. For files without extension, the first 512 bytes are sniffed.

CI pipeline usage

# GitHub Actions
- name: Validate config
  run: cv validate config/app.production.yaml --schema my-app-config
  env:
    CV_SERVER: ${{ secrets.CV_SERVER }}

The step fails (exit 1) if validation fails, blocking the deploy.

Troubleshooting

"schema not found"

The schema ID does not exist on the server. Run cv schemas list to see available schemas.

"format detection failed"

The file extension is not recognized and byte sniffing was inconclusive. Add the correct extension or use --format yaml|json|toml|env explicitly.