JSON Schema

The Sovrium app schema defines the complete structure of your application configuration. It is published as a standard JSON Schema (Draft-07), derived directly from the canonical Effect Schema (AppSchema). Use it for editor autocomplete, real-time validation, CI config checks, and programmatic verification.

Three artifacts share that single source of truth:

Artifact	Format	Generated by	Use it for
JSON Schema	JSON (Draft-07)	sovrium schema	Editor autocomplete, CI validation
@sovrium/types	TypeScript .d.ts	npm package	defineConfig() autocompletion in app.ts
AppSchema validator	runtime decode	sovrium validate	Verifying a config file before deploy

Generating the schema

The CLI prints the JSON Schema for the Sovrium app configuration. By default it writes to stdout; pass --output <path> to write a file instead.

# Print the JSON Schema to stdout
sovrium schema

# Write the JSON Schema to a file
sovrium schema --output app.schema.json

The generated document is a self-contained Draft-07 schema with a top-level $schema declaration, so any JSON-Schema-aware tool can consume it without further configuration. See the CLI Reference for the full command surface.

Root properties at a glance

The schema's root object accepts the following top-level properties. Every property except name is optional and layered on top.

Property	Type	Description
name	string	Application name (required)
version	string	App config version string
description	string	Human-readable description
tables	object[]	Data tables (see Tables Overview)
pages	object[]	Pages and their sections
forms	object[]	Standalone forms
auth	object	Authentication and RBAC configuration
theme	object	Design tokens (colors, fonts, spacing)
components	object[]	Reusable components
automations	object[]	Trigger/action workflows
connections	object[]	External service connections
languages	object	Internationalization / i18n
analytics	object	Privacy-friendly analytics
agents	object[]	AI agents

Schema URLs

Reference the hosted Sovrium JSON Schema by URL in your editor, CI pipeline, or validation scripts.

Versioned (recommended)

Pin to a specific version for production stability. The schema URL includes the exact package version.

https://sovrium.com/schema/app-0.10.0.json

Latest

Always points to the most recent version. Convenient for development, but may introduce breaking changes.

https://sovrium.com/schema/app.json

Editor integration

Add the JSON Schema to your editor for autocomplete, inline documentation, and real-time validation as you write your Sovrium config.

VS Code

VS Code supports JSON Schema natively for both JSON and YAML files (the YAML extension is required for .yaml/.yml).

Option 1: Add $schema directly to your config file

# yaml-language-server: $schema=https://sovrium.com/schema/app.json
name: my-app

You can also point the directive at a locally generated file:

# yaml-language-server: $schema=./app.schema.json
name: my-app

Option 2: Configure in VS Code settings.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, and other JetBrains IDEs support JSON Schema mapping natively.

Go to Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings. Click + to add a new mapping, paste the schema URL (or the path to a generated app.schema.json), and set the file pattern to match your config file (e.g., app.yaml or app.json).

TypeScript autocompletion with @sovrium/types

When you author your configuration as a TypeScript file (app.ts) instead of YAML/JSON, the zero-dependency @sovrium/types package gives you full IDE autocompletion, inline type errors, and jump-to-definition — backed by the same AppSchema.

bun add -d @sovrium/types

Wrap your config in defineConfig() to get type-checked autocompletion as you type:

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

Validating a config file

Use sovrium validate to check a configuration file against AppSchema before deploying. It accepts .json, .yaml, .yml, and .ts files, resolving any $ref includes first.

# Validate a YAML config
sovrium validate app.yaml

# Validate a JSON config
sovrium validate config.json

# Validate a TypeScript config
sovrium validate app.ts

On success it prints Valid configuration: <name> and exits 0. On failure it prints the structural decode errors (formatted as a tree) plus any post-decode findings — unknown field types and gated type: cloud actions — then exits 1.

Exit code	Meaning
0	Config is valid
1	Config is invalid (decode error, unknown field type, missing file)

Programmatic validation

For CI pipelines, run sovrium validate as a build step and gate on its exit code:

sovrium validate app.yaml || exit 1

For richer integrations, you can also serve the live schema over HTTP from a running instance (admin-only) and feed it to external tooling — see OpenAPI for the full HTTP schema surface.