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 →

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 685925e81c

ℹ️ 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]

Document the runtime CSP nonce placeholder

For users following the new generated reference, this points them to {{@csp_nonce}}, but the configuration parser only substitutes the literal {NONCE} placeholder (NONCE_PLACEHOLDER in src/webserver/content_security_policy.rs). A custom content_security_policy copied from this schema would therefore have no recognized nonce position, and is_enabled() would prevent SQLPage from sending the CSP header at all.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Keep the CSP setting non-nullable

This schema now validates "content_security_policy": null, but the generated Rust field is ContentSecurityPolicyTemplate, whose Deserialize implementation delegates to String::deserialize; when the key is present as null, startup fails instead of using the default. Users relying on editor/schema validation can end up with a configuration that passes validation but SQLPage cannot load.

Useful? React with 👍 / 👎.

[lovasoa]

@codex : no x-rust-type or anything fancy inside the schema definition. Use the standard to the best of its abilities, plus smart naming conventions and definitions to get a clean json schema definitions. If there are things that you see no way to cleanly encode in json schema or support through naming conventions, just use normal rust code. For instance, you could build a smaller sister struct that holds the additional parameters. Think about a clean design. the goal was refactoring and avoiding duplication between the code and docs, and we are already at a PR with 599 additions & 274 deletions !

[chatgpt-codex-connector]

Summary

• Removed Rust-specific schema extensions from the public configuration schema; the schema now uses standard JSON Schema properties without x-rust-* metadata. sqlpage/sqlpage.schema.jsonL1-L18
• Moved Rust-specific AppConfig generation logic into build.rs, using normal Rust code for field renames, serde attributes, and type overrides while inferring straightforward schema types from JSON Schema. build.rsL56-L79 build.rsL82-L179
• Fixed the CSP schema entry to document SQLPage’s actual {NONCE} runtime placeholder and made content_security_policy non-nullable to match runtime deserialization. sqlpage/sqlpage.schema.jsonL229-L232
• Regenerated the official configuration reference so the CSP placeholder documentation matches the cleaned schema. examples/official-site/configuration.sqlL44-L48
• Committed the changes as 247d322 (refactor: remove rust metadata from config schema) and created the PR “Remove Rust-specific metadata from configuration schema.”

Testing

• ✅ cargo fmt --all -- --check
• ✅ scripts/generate_configuration_reference.py --check
• ✅ scripts/check_configuration_examples.py
• ✅ git diff --check
• ✅ python3 - <<'PY' ... PY — verified the schema has no x-rust-* metadata, uses {NONCE}, and keeps content_security_policy as a string.
• ⚠️ cargo clippy --all-targets --all-features -- -D warnings — blocked by environment/toolchain issue: libsqlite3-sys build script uses unstable cfg_select with rustc 1.92.0.
• ⚠️ cargo test — blocked by the same libsqlite3-sys / unstable cfg_select build-script error.

View task →