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.

# 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

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

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.

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

Pages associées

• Fichiers de configuration : YAML et JSON — formats et ordre de résolution.
• Valider une configuration — vérifier une configuration scindée en une commande.
• Modèles et exemples — de vraies configurations avec cette disposition.