# Validating a Config

`sovrium validate` decodes a config file against `AppSchema` — the same schema the server decodes at boot — and reports every problem it finds. It touches no database, binds no port, and needs no environment, which makes it the cheapest place to catch a broken config.

```bash
sovrium validate app.yaml
sovrium validate config.json
sovrium validate app.ts
```

It accepts `.json`, `.yaml`, `.yml` and `.ts`, and resolves every `$ref` include before checking anything — so a config split across twenty files is validated as the one object it becomes.

## What success looks like

```text
Valid configuration: my-app
```

Exit code `0`. Because this is the same decode the server performs at startup, a config that validates will boot.

## What failure looks like

Problems print as an indented tree under a single header, and exit `1`.

**Read it from the bottom.** The tree walks down through the schema before it reaches your config, so the top is machinery — dozens of `From side refinement failure` lines — and the last two lines are the finding:

```text
Validation failed:
  { { { { App | filter } | filter } | filter } | filter }
  └─ From side refinement failure
     ... (many similar lines)
                 └─ App
                    └─ ["tabels"]
                       └─ is unexpected, expected: "name" | "version" | "description" | ...
```

That one says: you wrote `tabels`, and it is not a property. Piping through `tail` is a reasonable habit:

```bash
sovrium validate app.yaml 2>&1 | tail -5
```

## The three classes of error

| Class                 | Example                                 | Caught by                 |
| --------------------- | --------------------------------------- | ------------------------- |
| Structural            | `name` missing; a number given a string | The `AppSchema` decode    |
| Unrecognised property | `tabels:` instead of `tables:`          | Excess-property rejection |
| Unknown field type    | `type: web-site` on a table field       | The post-decode sweep     |

The second is worth dwelling on: `sovrium validate` rejects properties the schema does not know, rather than ignoring them. A typo'd key would otherwise be silently dropped, and the feature you thought you configured would simply never appear.

The third runs _after_ the decode, and prints plainly rather than as a tree:

```text
Validation failed:
  Unknown field type "web-site" in field "website"
```

With a [multi-file config](/en/docs/configuration-refs) the finding is attributed to the partial it came from — `companies.yaml: Unknown field type ...`.

:::callout
**Single-word field types are not flagged.** The sweep only reports a type it cannot recognise **and** that contains a `-` or `_`. A bare word like `colour` is treated as a plausible alias, passes validation, and fails later during SQL generation. Check spellings against [Field Types Overview](/en/docs/field-types-overview) rather than relying on this sweep alone.
:::

## Exit codes

| Exit code | Meaning                                                            |
| --------- | ------------------------------------------------------------------ |
| `0`       | Config is valid                                                    |
| `1`       | Config is invalid (decode error, unknown field type, missing file) |

Everything failed is `1`, so gating a pipeline is a single line:

```bash
sovrium validate app.yaml || exit 1
```

Run it before the deploy step. It is the last point where a bad config costs you seconds instead of a rollback.

## Programmatic validation

To validate inside a script rather than a shell, `validateConfig()` returns the result as data instead of exiting:

```typescript
import { validateConfig } from 'sovrium'

const result = validateConfig(JSON.parse(await Bun.file('app.json').text()))
if (!result.valid) console.error(result.errors.join('\n'))
```

It is deliberately looser than the CLI — it tolerates unrecognised properties and skips the unknown-field-type sweep. Use it as an in-process guard, and keep `sovrium validate` as the pre-deploy gate. Full details on [Validation & Schema Generation](/en/docs/typescript-validate).

## Related Pages

- [Project Commands](/en/docs/cli-project) — `sovrium validate` alongside `init`, `build`, `schema`.
- [Editor Setup](/en/docs/json-schema-editors) — catching structural errors as you type.
- [Multi-File Configs](/en/docs/configuration-refs) — how `$ref` files are attributed in errors.
- [Troubleshooting](/en/docs/troubleshooting) — the other errors a boot can print.