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

:::callout
**Interactive Schema Explorer.** Browse the full schema visually with the JSON Schema Viewer. Expand properties, view types, and explore nested structures.

[Open Schema Explorer ↗](https://json-schema.app/view/%23?url=https%3A%2F%2Fsovrium.com%2Fschema%2Fapp.json)
:::

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

```bash
# 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](/en/docs/cli) 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](/en/docs/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.11.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
# 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
# yaml-language-server: $schema=./app.schema.json
name: my-app
```

**Option 2: Configure in VS Code `settings.json`**

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

```bash
bun add -d @sovrium/types
```

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

```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
**Zero runtime dependencies.** `@sovrium/types` ships only TypeScript type definitions (generated from `AppSchema`), so it adds nothing to your bundle and stays MIT-licensed. The CLI accepts `app.ts` directly — `sovrium start app.ts`, `sovrium validate app.ts`.
:::

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

```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
```

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) |

:::callout
**Unknown field types are caught at validate time.** A field whose `type` is not one of the [49 known field types](/en/docs/field-types-overview) passes the structural decode but is flagged by `sovrium validate` (and would otherwise fail during SQL generation). Validating early surfaces these before runtime.
:::

## Programmatic validation

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

```bash
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](/en/docs/openapi) for the full HTTP schema surface.