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.

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

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:

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:

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:

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

With a multi-file config the finding is attributed to the partial it came from — companies.yaml: Unknown field type ....

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:

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:

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.

Related Pages

• Project Commands — sovrium validate alongside init, build, schema.
• Editor Setup — catching structural errors as you type.
• Multi-File Configs — how $ref files are attributed in errors.
• Troubleshooting — the other errors a boot can print.