# Validation et génération de schéma

Deux fonctions couvrent la moitié hors-ligne de l'API : vérifier une configuration sans rien démarrer, et émettre le JSON Schema qui décrit toutes les configurations.

## `validateConfig(config)`

Décode une valeur inconnue face à `AppSchema`. La fonction ne lève jamais : une configuration invalide revient sous forme de données, ce qui permet de signaler plusieurs problèmes d'un coup au lieu de mourir sur le premier.

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

const result = validateConfig({ name: 'My App' })

if (result.valid) {
  console.log(result.config.name)
} else {
  result.errors.forEach((error) => console.error(error))
}
```

### `ValidateConfigResult`

Le résultat est une **union discriminée**, pas un enregistrement à champs optionnels. Affinez sur `valid` avant de lire quoi que ce soit d'autre — TypeScript ne vous laissera pas faire autrement.

| Quand          | Forme                                         |
| -------------- | --------------------------------------------- |
| `valid: true`  | `{ valid: true, config: AppConfig }`          |
| `valid: false` | `{ valid: false, errors: readonly string[] }` |

`errors` contient des **chaînes de caractères**, une par ligne de l'arbre de décodage formaté, chacune nommant le chemin en échec et sa raison. Sur la branche de succès, la propriété `errors` n'existe pas du tout ; sur la branche d'échec, `config` non plus.

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

const untrusted: unknown = JSON.parse(await Bun.file('app.json').text())
const result = validateConfig(untrusted)

if (!result.valid) {
  console.error(`Invalid config:\n${result.errors.join('\n')}`)
  process.exit(1)
}

// `result.config` est un AppConfig ici, et seulement ici.
console.log(`Validated ${result.config.name}`)
```

:::callout
**Plus permissif que `sovrium validate`.** `validateConfig` exécute le même `AppSchema` que celui décodé au démarrage : propriétés obligatoires, membres d'énumération et erreurs de forme sont donc tous détectés. Deux choses qu'il ne fait **pas** : il tolère les propriétés supplémentaires non reconnues (le CLI, lui, les rejette), et il saute le balayage des types de champ inconnus. Voyez-le comme le garde-fou en mémoire, et [`sovrium validate`](/fr/docs/config-validation) comme la barrière avant déploiement.
:::

## `generateAppJsonSchema()`

Produit le JSON Schema (Draft-07) de la configuration d'application sous forme d'objet simple — le même document qu'affiche `sovrium schema`.

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

const schema = generateAppJsonSchema()

await Bun.write('app.schema.json', JSON.stringify(schema, null, 2))
```

Elle ne prend aucun argument et ne lit rien de l'environnement : le schéma est dérivé d'`AppSchema` lui-même, sa sortie ne dépend donc que de la version de Sovrium. On peut ainsi le régénérer en CI et comparer les différences — un changement dans le fichier est un changement du schéma, jamais de la machine.

Un usage courant consiste à figer le schéma à côté de la configuration, pour que les éditeurs valident face à la version exacte que vous déployez :

```typescript
// scripts/sync-schema.ts — à exécuter après chaque montée de version
import { generateAppJsonSchema } from 'sovrium'

await Bun.write('app.schema.json', JSON.stringify(generateAppJsonSchema(), null, 2))
```

```yaml
# app.yaml
# yaml-language-server: $schema=./app.schema.json
name: my-app
```

## Pages associées

- [Aperçu de l'API TypeScript](/fr/docs/typescript) — `AppConfig` et les autres fonctions.
- [Valider une configuration](/fr/docs/config-validation) — le vérificateur du CLI et ses balayages supplémentaires.
- [Schéma JSON](/fr/docs/json-schema) — les URLs du schéma hébergé.
- [Configuration de l'éditeur](/fr/docs/json-schema-editors) — y brancher VS Code ou JetBrains.