Config Files: YAML & JSON

A Sovrium app is one configuration object. This page covers writing it as a YAML or JSON file — the two formats you can hand to any command.

The same object, two spellings

YAML is the recommended default for hand-authoring: it takes comments, needs less punctuation, and diffs readably. JSON is the better target when something else generates the config.

# app.yaml
name: my-app
version: 1.0.0
description: A simple todo list

tables:
  - id: 1
    name: tasks
    fields:
      - { id: 1, name: title, type: single-line-text, required: true }
      - { id: 2, name: done, type: checkbox, default: false }

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A simple todo list",
  "tables": [
    {
      "id": 1,
      "name": "tasks",
      "fields": [
        { "id": 1, "name": "title", "type": "single-line-text", "required": true },
        { "id": 2, "name": "done", "type": "checkbox", "default": false }
      ]
    }
  ]
}

Either runs the same way:

sovrium start app.yaml
sovrium start app.json

Format detection

The format comes from the file extension, never from the content. .yaml and .yml go through the YAML parser, .json through the JSON parser, .ts and .mts are imported as modules. Anything else is refused up front:

Error: Unsupported file format: .toml

Supported formats: .json, .yaml, .yml, .ts

Because detection is by extension, every example in this documentation transcribes between YAML and JSON unchanged — the resulting object is identical.

Resolution order

A command takes its configuration from the first source that answers:

A file path always wins over the environment, so a container can carry a default APP_SCHEMA while a local run overrides it by naming a file.

Loading without a file

APP_SCHEMA holds the configuration itself rather than a path — useful for containers and one-off runs where mounting a file is more trouble than it is worth. See CLI Overview.

TypeScript with defineConfig

Moved to TypeScript Configs.

Multi-file configs with $ref

Moved to Multi-File Configs with $ref.

Validating a config

Moved to Validating a Config.

Next steps

• TypeScript Configs — the same object with autocomplete.
• Multi-File Configs — splitting a config that outgrew one file.
• Core Concepts — the anatomy of the configuration object.
• Schema Overview — the full root-property reference.