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

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 <chemin> pour écrire dans un fichier à la place.

# 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 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)
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.10.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-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-language-server: $schema=./app.schema.json
name: my-app

Option 2 : configurer dans le settings.json de VS Code

{
  "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.

bun add -d @sovrium/types

Enveloppez votre configuration dans defineConfig() pour obtenir une autocomplétion typée au fil de la saisie :

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 }],
    },
  ],
})

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.

# 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: <name> 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)

Validation programmatique

Pour les pipelines CI, exécutez sovrium validate comme étape de build et conditionnez sur son code de sortie :

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 pour la surface complète du schéma HTTP.