Valider une configuration

sovrium validate décode un fichier de configuration face à AppSchema — le schéma que le serveur décode au démarrage — et signale chaque problème trouvé. La commande ne touche aucune base de données, ne lie aucun port et n'exige aucun environnement : c'est donc l'endroit le moins coûteux pour attraper une configuration cassée.

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

Elle accepte .json, .yaml, .yml et .ts, et résout chaque inclusion $ref avant toute vérification — une configuration répartie sur vingt fichiers est donc validée comme l'objet unique qu'elle devient.

À quoi ressemble un succès

Valid configuration: my-app

Code de sortie 0. Il s'agit du même décodage que celui effectué au démarrage, et dans les deux sens : une configuration qui valide démarrera, et une configuration rejetée ici est une configuration que sovrium start et sovrium build refusent également.

À quoi ressemble un échec

Les problèmes s'affichent sous un seul en-tête Error: Validation failed., avec le code de sortie 1. Une propriété non reconnue est nommée, située, et accompagnée des clés que ce nœud accepte réellement :

Error: Validation failed.

  Unknown property 'tag' on component type 'text'
    at pages[0].components[0]
    Accepted here: type, children, props, content, interactions, responsive,
                   visibility, i18n, session, element, required

Quand l'orthographe est proche, le rapport le dit — Did you mean 'element'? — mais uniquement lorsque la correction est réellement déductible. Une suggestion produite à tout prix vous enverrait vers la mauvaise propriété : un nom sans voisin proche reçoit donc la liste des clés acceptées, et rien de plus.

Les problèmes structurels qui ne sont pas une clé parasite — un name manquant, un nombre là où une chaîne est attendue — s'affichent en arbre indenté, celui du décodeur. Lisez-le par le bas : il descend à travers le schéma avant d'atteindre votre configuration, le haut est donc de la mécanique et les dernières lignes portent le constat.

Une propriété par exécution. Une configuration comportant trois fautes en signale une. Corrigez, relancez.

Les quatre classes d'erreur

La deuxième est le contrat qui mérite d'être énoncé en entier, car il gouverne le fichier tout entier :

Avant ce contrat, une clé non reconnue était écartée et le serveur démarrait quand même — tag: 'h1' sur un composant text (la propriété s'écrit element) affichait donc un simple <p>, sans la moindre erreur. Le seul indice était l'absence de la fonctionnalité.

Cette exception est aussi la porte de sortie. Un attribut pour lequel Sovrium n'a pas de propriété de schéma a sa place dans props :

components:
  - type: text
    content: Hello
    props:
      data-analytics-id: hero # transmis tel quel

La troisième s'exécute après le décodage, et s'affiche en clair plutôt qu'en arbre :

Error: Validation failed.

  Unknown field type "web-site" in field "website"

Avec une configuration multi-fichiers, le constat est attribué à la partie dont il provient — companies.yaml: Unknown field type ....

La quatrième lit votre configuration face à elle-même : un composant nomme un champ, et la table à laquelle il est lié doit le déclarer.

Error: Validation failed.

  rowColorField: field 'statuss' not found in table 'orders'. Available: id, customer, status

Celle-ci change ce que votre application fait, pas seulement ce que dit le validateur. Un columns[].field, un series[].field de graphique, un colorField de kanban ou un fields[].field de formulaire qui nomme une colonne absente n'affichait rien et ne signalait rien : indiscernable d'une colonne dont les lignes sont simplement vides. Une vue listée sans la configuration qui la construit se comportait pareil : views: ['kanban'] sans kanbanGroupBy dessinait un onglet qui ne faisait rien une fois cliqué. Les deux sont désormais refusés par les trois commandes, si bien que l'erreur apparaît à votre bureau au lieu d'être livrée comme une fonctionnalité qui a l'air délibérée.

Les colonnes système (id, les horodatages, les colonnes d'auteur) se résolvent toujours : elles existent sans figurer dans fields[]. Un composant lié à une source système plutôt qu'à une table est ignoré, ses colonnes décrivant la réponse d'un point d'accès et non une table déclarée.

Codes de sortie

Tout échec vaut 1 : contrôler un pipeline tient donc en une ligne.

sovrium validate app.yaml || exit 1

Exécutez-la avant l'étape de déploiement. C'est le dernier point où une mauvaise configuration coûte des secondes plutôt qu'un retour arrière.

Valider depuis une configuration

Pour vérifier une configuration depuis une application en cours d'exécution plutôt que depuis un terminal — un webhook qui reçoit une configuration soumise, un audit planifié — utilisez l'action d'automatisation sovrium:validateConfig. Elle exécute ce même décodeur, sans effet de bord ni démarrage, et expose {{steps.<name>.valid}} et {{steps.<name>.errors}} :

automations:
  - name: check-submitted-config
    trigger:
      type: webhook
      method: POST
    actions:
      - name: check
        type: sovrium
        operator: validateConfig
        props:
          config: '{{trigger.data.config}}'
          format: auto

Il n'existe pas d'alternative plus permissive en cours d'exécution, et c'est délibéré : un second validateur qui tolérerait ce que celui-ci rejette signifierait qu'une configuration peut franchir une barrière et échouer à l'autre. Le candidat est également lu tel quel — un {{...}} ou un $env.X présent dans la configuration soumise est validé comme du texte littéral, jamais résolu — de sorte que le verdict décrit ce que vous avez transmis, et non une copie réécrite. Détails complets sur Validation et génération de schéma et Actions d'automatisation.

Pages associées

• Commandes de projet — sovrium validate aux côtés d'init, build, schema.
• Validation et génération de schéma — sovrium validate et sovrium schema côte à côte.
• Configuration de l'éditeur — attraper les erreurs structurelles à la frappe.
• Configurations multi-fichiers — comment les fichiers $ref sont attribués dans les erreurs.
• Dépannage — les autres erreurs qu'un démarrage peut afficher.