Description
We want to modernize our configuration management by leveraging Zod v4's native JSON Schema conversion feature to use Zod as the primary schema definition while generating JSON Schema for Ruby backend compatibility.
Description
Currently we're considering implementing a unified configuration schema approach. We'd like to explore using Zod v4 as the source of truth for our configuration schema, taking advantage of the new native z.toJSONSchema() function to generate the JSON Schema that Ruby consumes during startup validation.
This approach would provide better TypeScript developer experience while maintaining full compatibility with our Ruby configuration validation needs. We already have extensive Zod schemas for system settings in our API layer that we can build upon.
TODO
- Upgrade to Zod v4 to access native JSON Schema conversion
- Create unified Zod configuration schema in
src/schemas/config.ts - Leverage existing
systemSettingsSchemafrom colonel API endpoints - Implement build script using
z.toJSONSchema()to generateetc/config.schema.json - Update Ruby configuration loading to use generated JSON Schema
- Add schema generation to build pipeline with verification
- Update documentation in
etc/README.md - Migrate existing Ruby DEFAULTS hash to use generated defaults
- Migrate OT::Config from module to class
- Provide facility to re-merge static and dynamic config on the fly
- Provide facility for "unmodifiable" static config for the lifetime of the process. So if
OT.confremains the entry point for the full merged static+dynamic configuration, we can use something likeOT::Config.staticorOT::Config.static_configurationas the frozen hash we use when we merge with dynamic configuration.
Technical Considerations
- Native Conversion: Zod v4's
z.toJSONSchema()eliminates third-party dependency and provides better conversion fidelity - Schema Integration: Build upon existing
systemSettingsSchemaand related schemas already defined insrc/schemas/api/endpoints/colonel.ts - Default Value Extraction: Leverage JSON Schema defaults generation to replace Ruby DEFAULTS hash
- Build Pipeline: Ensure generated schema is validated in CI and committed for Ruby consumption
- Backward Compatibility: Maintain compatibility with existing Ruby configuration validation logic
Existing Schema Foundation
We already have comprehensive Zod schemas for system settings including:
- Interface configuration (UI/API settings, branding, navigation)
- Secret options and TTL settings
- Mail/Truemail configuration
- Diagnostics and Sentry integration
- Rate limiting configuration
- Colonel/admin functionality
These can serve as the foundation for our unified configuration schema.
Opportunities for Improvement
- Zero Dependencies: Native JSON Schema conversion eliminates external library dependency
- Type Safety: Full TypeScript intellisense and validation throughout configuration handling
- Schema Reuse: Leverage existing API endpoint schemas for consistent validation
- Single Source of Truth: Eliminate schema drift between frontend API validation and backend config validation
- Better Developer Experience: Zod's composition features enable cleaner schema organization
References
Sub-issues
Metadata
Metadata
Assignees
Labels
Type
Projects
Status