Skip to main content
View as Markdown

Schema Overview

The complete reference for the Sovrium app schema. A declarative configuration object with 18 root properties — only name is required. Everything else is optional, enabling progressive complexity from a minimal app identifier to a full-stack application.

Schema Structure

name: my-app # App identifier (required)
version: 1.0.0 # SemVer version
description: My application # One-line description

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

Root Properties

The app schema has 18 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.
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 three scalar root properties — name, version, and description — are covered on the 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). 
# Valid names
name: my-app
name: task-tracker-v2
name: '@acme/dashboard'

version

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

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 for the full guide.

# YAML format (recommended)
name: my-app
version: 1.0.0
tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text }
{
  "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 to check these rules ahead of deployment.