# Schema Overview

The Sovrium app schema is a declarative configuration object with 19 root properties. Only `name` is required; everything else is optional. That lets an app grow in steps — from a single identifier to a full-stack application — without rewriting what came before.

## Schema Structure

```yaml
name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description
badge: false # "Built with Sovrium" badge (shown by default)

tables: [...] # Data models with 49 field types
pages: [...] # Server-rendered pages (~80 component types)
forms: [...] # Standalone forms capturing submissions
auth: { ... } # Authentication, roles, RBAC, 2FA
theme: { ... } # Design tokens (colors, fonts, etc.)
languages: { ... } # Multi-language support ($t: syntax)

automations: [...] # Event-driven workflows (triggers + actions)
actions: [...] # Reusable action templates ($ref)
connections: [...] # External-service credentials
agents: [...] # AI agents acting under an auth role
buckets: [...] # Named file-storage containers

components: [...] # Reusable UI templates ($ref, $variable)
analytics: { ... } # Cookie-free, first-party analytics
env: { ... } # Declared automation env vars ($env.NAME)
scripts: { ... } # Global page scripts
```

:::callout
**Progressive complexity.** Only `name` is required. Add `tables`, `theme`, `pages`, `auth`, and other sections as your app grows.
:::

## Root Properties

The app schema has 19 root properties. Only `name` is required.

| Property      | Type              | Description                                                                                                        |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `name`        | string (required) | App identifier following npm naming conventions. Lowercase, max 214 chars, supports scoped format (`@scope/name`). |
| `version`     | string            | Semantic Versioning 2.0.0 string (e.g. `1.0.0`, `2.0.0-beta.1`). Feeds the immutable version ledger.               |
| `description` | string            | Single-line app description (max 2000 chars). No line breaks. Unicode and emojis supported.                        |
| `badge`       | boolean           | "Built with Sovrium" badge on all pages. Shown by default; `badge: false` removes it — free, one line, forever.    |
| `tables`      | array             | Data models with 49 field types, relationships, indexes, permissions, and views.                                   |
| `theme`       | object            | Design tokens: colors, fonts, spacing, shadows, animations, breakpoints, and border radius.                        |
| `languages`   | object            | Multi-language support with `$t:` translation syntax, browser detection, and URL routing.                          |
| `auth`        | object            | Authentication strategies (email/password, magic link, OAuth), roles, RBAC, sessions, and two-factor.              |
| `analytics`   | object \| boolean | Privacy-friendly, cookie-free, first-party analytics. Set to `true` for defaults or configure with options.        |
| `components`  | array             | Reusable UI templates with `$ref` referencing and `$variable` substitution.                                        |
| `pages`       | array             | Server-rendered pages with ~80 component types, SEO metadata, and i18n support.                                    |
| `forms`       | array             | Standalone forms that capture submissions into a table or trigger an automation.                                   |
| `connections` | array             | Reusable credentials for external services: OAuth2, API key, basic auth, and bearer token.                         |
| `env`         | object            | Declared environment variables resolved at runtime, referenced in actions as `$env.NAME` (never logged).           |
| `actions`     | array             | Reusable action templates referenced from automations via `$ref` with `$vars`.                                     |
| `automations` | array             | Event-driven workflows: a trigger fires, a sequence of actions runs.                                               |
| `agents`      | array             | AI agents acting on behalf of an auth role within a constrained tool set, with approval gates and rate limits.     |
| `buckets`     | array             | Named storage containers with per-bucket file limits and access permissions.                                       |
| `scripts`     | object            | Global scripts loaded on every page before page-level scripts.                                                     |

## Property Details

Detailed rules and constraints for the scalar root properties — `name`, `version`, `description`, and `badge` — are covered on the [App Metadata](/en/docs/app-metadata) page, which also documents the version ledger, drift detection, and draft staleness.

### `name`

The app name follows npm naming conventions. Lowercase, URL-safe, and unique within your deployment.

| Constraint | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| Pattern    | `^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$`. Lowercase letters, digits, hyphens, dots, tildes. |
| Max length | 214 characters maximum (including `@scope/` prefix if scoped).                                               |
| Scoped     | Supports npm-style scoped packages: `@scope/name` (e.g. `@acme/dashboard`).                                  |

```yaml
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'
```

### `version`

Follows Semantic Versioning 2.0.0 ([semver.org](https://semver.org)). Format: `MAJOR.MINOR.PATCH` with optional pre-release and build metadata.

```yaml
version: 1.0.0 # Stable release
version: 2.0.0-beta.1 # Pre-release
version: 1.0.0+build.42 # Build metadata
```

### `description`

A single-line text describing the application. Displayed in the admin UI and metadata.

| Constraint | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| Format     | Single line only. No line breaks (`\n`) allowed.              |
| Max length | 2000 characters maximum.                                      |
| Unicode    | Full Unicode support including emojis and special characters. |

## Configuration Formats

Sovrium accepts YAML, JSON, and TypeScript configuration. YAML is recommended for readability; JSON suits programmatic generation; TypeScript adds type safety via `@sovrium/types`. Large configs can be split across files with `$ref`. See [Configuration Files](/en/docs/configuration-files) for the full guide.

```yaml
# YAML format (recommended)
name: my-app
version: 1.0.0
tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text }
```

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [{ "id": 1, "name": "title", "type": "single-line-text" }]
    }
  ]
}
```

## Cross-section validation

Root sections are validated _together_, not in isolation. Sovrium rejects a config before the server starts when, for example:

- a `user`/`created-by`/`updated-by` field exists but `auth` is not configured;
- a table or bucket permission names a role that is not declared;
- an attachment field references a `bucket` not present in `buckets`;
- a record automation trigger or action references a table that does not exist;
- an automation `$ref` action, AI agent reference, or form trigger names something undeclared.

Run [`sovrium validate`](/en/docs/cli) to check these rules ahead of deployment.

## Related Pages

- [App Metadata](/en/docs/app-metadata) — `name`, `version`, `description`, `badge`, version ledger, drift detection.
- [Tables Overview](/en/docs/tables-overview) — data models and 49 field types.
- [Pages Overview](/en/docs/pages-overview) — ~80 component types for server-rendered pages.
- [Forms Overview](/en/docs/forms-overview) — standalone forms and submissions.
- [Auth Overview](/en/docs/auth-overview) — strategies, roles, and RBAC.
- [Automations Overview](/en/docs/automations-overview) — triggers, actions, and connections.
- [AI Overview](/en/docs/ai-overview) — agents and AI-native fields.
- [Buckets Overview](/en/docs/buckets-overview) — file-storage containers.
- [Records Overview](/en/docs/records-overview) — querying and mutating rows at runtime.
- [Theme](/en/docs/theme) · [Responsive Design](/en/docs/responsive-design) · [Animations](/en/docs/animations) · [Languages](/en/docs/languages).