Make JSON Schema the configuration source of truth

[lovasoa]

Motivation

• Replace the ad-hoc configuration docs and handwritten AppConfig with a single machine-readable source so editor validation, runtime parsing, and documentation stay consistent.
• Use the JSON Schema to drive code generation so the in-memory Rust configuration matches the published schema and reduces drift between docs and code.
• Ensure all checked-in example configurations are validated against the live schema so examples remain usable and editor-friendly.

Description

• Add a checked-in Draft 2020-12 JSON Schema at sqlpage/sqlpage.schema.json that declares types, defaults, descriptions and x-rust-* metadata for code generation.
• Generate the AppConfig Rust struct at build time from the JSON Schema via build.rs and include it with include!(concat!(env!("OUT_DIR"), "/app_config.rs")); instead of the handwritten struct in src/app_config.rs.
• Add scripts/generate_configuration_reference.py to produce examples/official-site/configuration.sql from the schema and scripts/check_configuration_examples.py to validate that every example JSON references the live schema, and convert existing example YAML files to schema-linked JSON with "$schema" set.
• Update docs and site content to point to the generated official-site reference (/configuration.sql) and add a unit test example_json_configuration_deserializes to ensure the checked-in example sqlpage/sqlpage.json deserializes into AppConfig.

Testing

• Ran formatting and linting checks with cargo fmt --all -- --check and cargo clippy --all-targets --all-features -- -D warnings, which succeeded.
• Ran the full Rust test suite with cargo test, which completed with all unit and integration tests passing.
• Validated generated artifacts and examples with scripts/generate_configuration_reference.py --check and scripts/check_configuration_examples.py, and used npx ajv-cli validate --strict=false --spec=draft2020 -s sqlpage/sqlpage.schema.json -d 'sqlpage/sqlpage.json' -d 'examples/**/sqlpage.json', all of which succeeded (AJV emitted format warnings only).
• Performed cargo check --all-features to verify build-time code generation integration, which succeeded.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ac4a3ec183

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve the non-option configuration guides

For users following existing repository links into configuration.md, this replacement removes the guides for OIDC setup, custom components, configuration/web-root directories, connection initialization and cleanup scripts, migrations, and custom routes. The linked official reference is only a generated option table, so it cannot replace those sections; for example, existing links from README.md and CHANGELOG.md now lead to a page that no longer contains the referenced operational guidance. Keep the non-option sections in this file or move them to stable linked destinations.

Useful? React with 👍 / 👎.

[lovasoa]

@codex restore the missing docs

[chatgpt-codex-connector]

Summary

• Restored the missing OpenID Connect setup documentation, including application address configuration and identity-provider examples. configuration.mdL36-L88
• Restored operational guides for custom components and configuration/web-root directories. configuration.mdL98-L145
• Restored connection initialization and cleanup scripts, migrations, and custom URL route documentation. configuration.mdL147-L226
• Committed the changes in commit d28a960 (docs: restore configuration guides) and created the pull request “Restore operational configuration guides.”

Testing

• ✅ python3 - <<'PY' ... PY — verified all requested restored section headings are present.
• ✅ git diff --check — completed without whitespace errors.

View task →