validate-config

# 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

```bash
# 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

```bash
# 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

```json
{
  "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

```yaml
# 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.