# Configurations multi-fichiers avec `$ref`

Un fichier unique cesse d'être lisible aux alentours de la troisième table. `$ref` scinde une configuration YAML ou JSON sur autant de fichiers que vous le souhaitez, sans rien changer à l'objet obtenu.

Tout objet dont la **seule** clé est `$ref`, et dont la valeur est un chemin relatif, est remplacé par le contenu analysé de ce fichier.

```yaml
# app.yaml
name: crm-workspace
version: 2.0.0

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml
  - $ref: ./config/tables/deals.yaml

pages:
  - $ref: ./config/pages/sign-in.yaml
  - $ref: ./config/pages/companies.yaml

agents:
  - $ref: ./config/agents/records-assistant.yaml
```

```yaml
# config/tables/companies.yaml
id: 1
name: Companies
fields:
  - { id: 1, name: name, type: single-line-text, required: true }
  - { id: 2, name: website, type: url }
```

## Règles

| Règle                | Comportement                                                                                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Résolution de chemin | Les chemins `$ref` se résolvent relativement au fichier qui les contient, et non au répertoire de travail.                                                  |
| Formats mixtes       | Un fichier racine YAML peut faire `$ref` vers une partie JSON et vice versa — chaque fichier est analysé selon son extension.                               |
| Éléments de tableau  | Un `$ref` peut remplacer un élément entier de tableau (`- $ref: ...`) ou une valeur d'objet entière.                                                        |
| Moment de résolution | Tous les `$ref` sont résolus en un seul objet _avant_ la validation du schéma, de sorte que les vérifications inter-sections voient l'application complète. |

Résoudre avant la validation est ce qui rend la scission sûre : une règle comme « une automatisation d'enregistrement doit référencer une table existante » reste vérifiée sur l'application entière, même quand l'automatisation et la table vivent dans des fichiers différents.

## La convention `config/`

`sovrium init` génère — et les modèles intégrés suivent — une seule forme : **un fichier par entité de collection, un fichier par singleton, les scalaires restent en ligne.**

```text
app.yaml               # name, version et la carte des $ref
config/
  auth.yaml            # singleton
  theme.yaml           # singleton
  tables/
    companies.yaml     # une entité par fichier
    contacts.yaml
  pages/
    sign-in.yaml
```

Rien n'impose cette disposition — `$ref` accepte n'importe quel chemin relatif. Elle gagne sa place en faisant du fichier racine une table des matières : le contenu de l'application se lit sans ouvrir quoi que ce soit d'autre.

## Quand scinder

Gardez une configuration dans un seul fichier tant qu'elle est petite. Scindez dès qu'une section grossit assez pour mériter son propre nom — en pratique, passé les deux premières tables ou pages, ou dès qu'un thème devient conséquent.

La validation attribue les erreurs au fichier dont elles proviennent : une faute dans une partie est donc signalée sur cette partie, pas sur la racine.

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

:::callout
**`$ref` ne concerne que YAML et JSON.** Les configurations TypeScript se composent avec des `import` ordinaires — voir [Configurations TypeScript](/fr/docs/configuration-typescript).
:::

## Pages associées

- [Fichiers de configuration : YAML et JSON](/fr/docs/configuration-files) — formats et ordre de résolution.
- [Valider une configuration](/fr/docs/config-validation) — vérifier une configuration scindée en une commande.
- [Modèles et exemples](/fr/docs/templates-examples) — de vraies configurations avec cette disposition.