# Schéma JSON Le schéma d'application Sovrium définit la structure complète de la configuration de votre application. Il est publié sous forme de **schéma JSON standard (Draft-07)**, dérivé directement du schéma Effect canonique (`AppSchema`). Utilisez-le pour l'autocomplétion dans l'éditeur, la validation en temps réel, les vérifications de configuration en CI et la vérification programmatique. Trois artefacts partagent cette source unique de vérité : | Artefact | Format | Généré par | À utiliser pour | | -------------------- | ------------------ | ------------------ | ------------------------------------------------------ | | Schéma JSON | JSON (Draft-07) | `sovrium schema` | Autocomplétion dans l'éditeur, validation CI | | `@sovrium/types` | TypeScript `.d.ts` | paquet npm | Autocomplétion `defineConfig()` dans `app.ts` | | Validateur AppSchema | décodage runtime | `sovrium validate` | Vérifier un fichier de configuration avant déploiement | :::callout **Explorateur de schéma interactif.** Parcourez le schéma complet visuellement avec le JSON Schema Viewer. Dépliez les propriétés, consultez les types et explorez les structures imbriquées. [Ouvrir l'explorateur de schéma ↗](https://json-schema.app/view/%23?url=https%3A%2F%2Fsovrium.com%2Fschema%2Fapp.json) ::: ## Générer le schéma La CLI affiche le schéma JSON de la configuration d'application Sovrium. Par défaut, elle écrit sur la sortie standard ; passez `--output ` pour écrire dans un fichier à la place. ```bash # Print the JSON Schema to stdout sovrium schema # Write the JSON Schema to a file sovrium schema --output app.schema.json ``` Le document généré est un schéma Draft-07 autonome avec une déclaration `$schema` de premier niveau, de sorte que tout outil compatible avec JSON Schema peut le consommer sans configuration supplémentaire. Consultez la [Référence CLI](/fr/docs/cli) pour la surface complète des commandes. ## Propriétés racine en un coup d'œil L'objet racine du schéma accepte les propriétés de premier niveau suivantes. Chaque propriété sauf `name` est optionnelle et vient se superposer. | Propriété | Type | Description | | ------------- | ---------- | ---------------------------------------------------------------------- | | `name` | `string` | Nom de l'application (requis) | | `version` | `string` | Chaîne de version de la configuration | | `description` | `string` | Description lisible par un humain | | `tables` | `object[]` | Tables de données (voir [Aperçu des tables](/fr/docs/tables-overview)) | | `pages` | `object[]` | Pages et leurs sections | | `forms` | `object[]` | Formulaires autonomes | | `auth` | `object` | Configuration de l'authentification et du RBAC | | `theme` | `object` | Tokens de design (couleurs, polices, espacements) | | `components` | `object[]` | Composants réutilisables | | `automations` | `object[]` | Flux de travail déclencheur/action | | `connections` | `object[]` | Connexions à des services externes | | `languages` | `object` | Internationalisation / i18n | | `analytics` | `object` | Analytique respectueuse de la vie privée | | `agents` | `object[]` | Agents IA | ## URLs du schéma Référencez le schéma JSON Sovrium hébergé par son URL dans votre éditeur, votre pipeline CI ou vos scripts de validation. ### Versionné (recommandé) Épinglez à une version spécifique pour la stabilité en production. L'URL du schéma inclut la version exacte du paquet. ``` https://sovrium.com/schema/app-0.11.0.json ``` ### Dernière version Pointe toujours vers la version la plus récente. Pratique pour le développement, mais peut introduire des changements incompatibles. ``` https://sovrium.com/schema/app.json ``` ## Intégration à l'éditeur Ajoutez le schéma JSON à votre éditeur pour bénéficier de l'autocomplétion, de la documentation en ligne et de la validation en temps réel au fil de l'écriture de votre configuration Sovrium. ### VS Code VS Code prend en charge nativement le schéma JSON pour les fichiers JSON et YAML (l'extension YAML est requise pour les fichiers `.yaml`/`.yml`). **Option 1 : ajouter `$schema` directement dans votre fichier de configuration** ```yaml # yaml-language-server: $schema=https://sovrium.com/schema/app.json name: my-app ``` Vous pouvez également faire pointer la directive vers un fichier généré localement : ```yaml # yaml-language-server: $schema=./app.schema.json name: my-app ``` **Option 2 : configurer dans le `settings.json` de VS Code** ```json { "yaml.schemas": { "https://sovrium.com/schema/app.json": ["app.yaml", "*.sovrium.yaml"] }, "json.schemas": [ { "fileMatch": ["app.json", "*.sovrium.json"], "url": "https://sovrium.com/schema/app.json" } ] } ``` ### JetBrains IntelliJ IDEA, WebStorm et les autres IDE JetBrains prennent en charge nativement le mappage de schéma JSON. Allez dans **Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings**. Cliquez sur **+** pour ajouter un nouveau mappage, collez l'URL du schéma (ou le chemin vers un fichier `app.schema.json` généré) et définissez le motif de fichier pour correspondre à votre fichier de configuration (par exemple, `app.yaml` ou `app.json`). ## Autocomplétion TypeScript avec `@sovrium/types` Lorsque vous rédigez votre configuration sous forme de fichier TypeScript (`app.ts`) plutôt qu'en YAML/JSON, le paquet sans dépendance `@sovrium/types` vous offre l'autocomplétion complète dans l'IDE, les erreurs de type en ligne et le saut à la définition — le tout adossé au même `AppSchema`. ```bash bun add -d @sovrium/types ``` Enveloppez votre configuration dans `defineConfig()` pour obtenir une autocomplétion typée au fil de la saisie : ```typescript import { defineConfig } from '@sovrium/types' export default defineConfig({ name: 'my-app', description: 'My Sovrium application', tables: [ { id: 1, name: 'contacts', fields: [{ id: 1, name: 'email', type: 'email', required: true }], }, ], }) ``` :::callout **Zéro dépendance d'exécution.** `@sovrium/types` ne livre que des définitions de types TypeScript (générées à partir d'`AppSchema`), il n'ajoute donc rien à votre bundle et reste sous licence MIT. La CLI accepte directement `app.ts` — `sovrium start app.ts`, `sovrium validate app.ts`. ::: ## Valider un fichier de configuration Utilisez `sovrium validate` pour vérifier un fichier de configuration par rapport à `AppSchema` avant déploiement. Il accepte les fichiers `.json`, `.yaml`, `.yml` et `.ts`, en résolvant d'abord toute inclusion `$ref`. ```bash # Validate a YAML config sovrium validate app.yaml # Validate a JSON config sovrium validate config.json # Validate a TypeScript config sovrium validate app.ts ``` En cas de succès, il affiche `Valid configuration: ` et se termine avec le code `0`. En cas d'échec, il affiche les erreurs de décodage structurel (formatées en arborescence) ainsi que tout constat post-décodage — types de champ inconnus et actions `type: cloud` restreintes — puis se termine avec le code `1`. | Code de sortie | Signification | | -------------- | ------------------------------------------------------------------------------------------- | | `0` | La configuration est valide | | `1` | La configuration est invalide (erreur de décodage, type de champ inconnu, fichier manquant) | :::callout **Les types de champ inconnus sont détectés au moment de la validation.** Un champ dont le `type` ne fait pas partie des [49 types de champ connus](/fr/docs/field-types-overview) passe le décodage structurel mais est signalé par `sovrium validate` (et échouerait sinon lors de la génération SQL). Valider tôt fait remonter ces problèmes avant l'exécution. ::: ## Validation programmatique Pour les pipelines CI, exécutez `sovrium validate` comme étape de build et conditionnez sur son code de sortie : ```bash sovrium validate app.yaml || exit 1 ``` Pour des intégrations plus riches, vous pouvez également servir le schéma en direct via HTTP depuis une instance en cours d'exécution (réservé aux administrateurs) et l'alimenter vers des outils externes — consultez [OpenAPI](/fr/docs/openapi) pour la surface complète du schéma HTTP.