Skip to content

Commit ccdd59f

Browse files
josecelanojosecelano
committed
feat: add JSON Schema generation feature specification
1 parent 8cbf93e commit ccdd59f

File tree

4 files changed

+981
-0
lines changed

4 files changed

+981
-0
lines changed

‎docs/features/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Feature documentation serves to:
1515

1616
| Feature | Status | Priority | Created |
1717
| -------------------------------------------------------------------- | -------------- | -------- | ------------ |
18+
| [JSON Schema Generation](./json-schema-generation/README.md) | 📋 Specified | High | Dec 12, 2025 |
1819
| [Hetzner Provider Support](./hetzner-provider-support/README.md) | 📋 Specified | High | Dec 1, 2025 |
1920
| [Register Existing Instances](./import-existing-instances/README.md) | 📋 Specified | High | Nov 19, 2025 |
2021
| [Linter Auto-fix](./linter-auto-fix/README.md) | 📋 Specified | Medium | Oct 9, 2025 |

‎docs/features/json-schema-generation/README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# JSON Schema Generation for Environment Configuration
2+
3+
Generate JSON Schema from Rust types to help users validate and edit environment configuration files.
4+
5+
## 📄 Documents
6+
7+
### [specification.md](./specification.md)
8+
9+
The main feature specification including:
10+
11+
- Overview and problem statement
12+
- Feature goals
13+
- Proposed solution using Schemars crate
14+
- Implementation details
15+
- Definition of done
16+
- Testing strategy
17+
18+
### [questions.md](./questions.md)
19+
20+
Clarifying questions answered by stakeholders:
21+
22+
- Scope and requirements ✅
23+
- Technical approach ✅
24+
- Priority and timeline ✅
25+
- Success criteria ✅
26+
- Risk assessment ✅
27+
- Risk assessment
28+
29+
## 📋 Status
30+
31+
**Current Phase**: Ready for Implementation
32+
33+
**Completed**:
34+
35+
1. ✅ Create feature specification
36+
2. ✅ Create questions document
37+
3. ✅ Answer clarifying questions
38+
4. ✅ Update specification based on answers
39+
5. ⏳ Begin implementation
40+
41+
**Next Steps**:
42+
43+
1. Answer clarifying questions in questions.md
44+
2. Update specification based on answers
45+
3. Add Schemars dependency to Cargo.toml
46+
4. Implement schema generation in config types
47+
5. Add new CLI subcommand `create schema`
48+
6. Update template command output with schema hint
49+
50+
## 🎯 Quick Summary
51+
52+
Add a new `create schema` subcommand that generates JSON Schema from the Rust configuration types using the Schemars crate. This helps users validate their environment JSON files with IDE support, better error messages, and auto-completion.
53+
54+
**Key Points**:
55+
56+
- **Problem**: Users editing environment JSON files lack validation, auto-completion, and clear documentation of valid values
57+
- **Solution**: Generate JSON Schema from Rust types using Schemars, expose via CLI command
58+
- **Status**: Ready for implementation - questions answered, specification refined
59+
- **Benefits**: Better UX through IDE integration, fewer configuration errors, self-documenting schema, AI agent support
60+
- **Priority**: High - significantly enhances user experience, especially for AI-assisted configuration
61+
62+
## 🔗 Related Documentation
63+
64+
- [Development Principles](../../development-principles.md)
65+
- [Contributing Guidelines](../../contributing/README.md)
66+
- [User Guide - Create Command](../../user-guide/commands/create.md)
67+
- [Schemars Crate Documentation](https://graham.cool/schemars/)

‎docs/features/json-schema-generation/questions.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Clarifying Questions for JSON Schema Generation
2+
3+
This document contains questions to clarify requirements, scope, and priorities before implementation begins. Product owners or stakeholders should answer these questions directly in the document.
4+
5+
---
6+
7+
## 🔍 Scope and Requirements
8+
9+
### 1. **Core Functionality**
10+
11+
**Question**: What is the minimum viable functionality for this feature?
12+
13+
**Your Answer**:
14+
15+
- Generate valid JSON Schema from Rust configuration types
16+
- Provide CLI command `create schema` with optional output path
17+
- Print schema to stdout if no path provided
18+
- Write schema to file if path provided
19+
- Update `create template` command output to mention schema generation
20+
21+
All of them.
22+
23+
### 2. **Out of Scope**
24+
25+
**Question**: What is explicitly NOT included in this feature?
26+
27+
**Your Answer**:
28+
29+
- Schema validation during `create template` (validation already exists in Rust deserialization)
30+
- IDE plugins or extensions for schema integration
31+
- Schema versioning or migration
32+
- Online schema hosting/registry
33+
- Schema for other configuration formats (TOML, YAML)
34+
35+
Correct, all of them.
36+
37+
### 3. **User Experience**
38+
39+
**Question**: How should users interact with this feature? What's the expected workflow?
40+
41+
**Your Answer**:
42+
43+
1. User runs `cargo run create schema` to see schema or `cargo run create schema ./schema.json` to save it
44+
2. User configures their IDE/editor to use the schema for validation (e.g., VS Code settings)
45+
3. When editing environment JSON files, IDE provides validation, auto-completion, and documentation
46+
4. Optional: User can commit schema file to repository for team consistency
47+
48+
Correct, all of them.
49+
50+
## 🎯 Technical Approach
51+
52+
### 4. **Implementation Strategy**
53+
54+
**Question**: Are there specific technical approaches or patterns we should follow?
55+
56+
**Your Answer**:
57+
58+
- Use Schemars crate to derive JSON Schema from Rust types
59+
- Add `#[derive(JsonSchema)]` to all config types in `src/application/command_handlers/create/config/`
60+
- Create new command handler in application layer
61+
- Follow existing three-level pattern (Command → Step → Action)
62+
- Ensure schema includes descriptions from Rust doc comments
63+
64+
Correct, all of them.
65+
66+
### 5. **Integration Points**
67+
68+
**Question**: How does this feature integrate with existing components?
69+
70+
**Your Answer**:
71+
72+
- Uses existing config types in `src/application/command_handlers/create/config/`
73+
- Adds new subcommand to CLI parser in presentation layer
74+
- Updates `create template` command to mention schema availability
75+
- No changes to environment creation, provisioning, or deployment logic
76+
77+
Correct, all of them.
78+
79+
### 6. **Performance Requirements**
80+
81+
**Question**: Are there specific performance requirements or constraints?
82+
83+
**Your Answer**:
84+
85+
- Schema generation should complete in <100ms (it's a simple reflection operation)
86+
- Schema file size expected to be <100KB
87+
- No runtime performance impact on other commands
88+
89+
No specific performance requirements. Only need to ensure it doesn't hang or crash or it takes an unreasonable amount of time.
90+
91+
## 📊 Priority and Timeline
92+
93+
### 7. **Priority Level**
94+
95+
**Question**: What is the priority of this feature? (High | Medium | Low)
96+
97+
**Your Answer**: **Medium** - Improves developer experience but not blocking for core functionality
98+
99+
It's high priority as it significantly enhances user experience when configuring environments.
100+
And specifically for users who are using AI agents to help them write configuration files, having a JSON Schema is very beneficial.
101+
102+
### 8. **Timeline Expectations**
103+
104+
**Question**: Is there a target date or sprint for completion?
105+
106+
**Your Answer**: No specific deadline. Can be implemented incrementally alongside other work.
107+
108+
Correct, no specific deadline.
109+
110+
### 9. **Dependencies**
111+
112+
**Question**: Does this feature depend on other work being completed first?
113+
114+
**Your Answer**:
115+
116+
- No blockers - existing config types are stable
117+
- Should review if Hetzner provider config is finalized before implementation
118+
- May want to coordinate with any ongoing config refactoring work
119+
120+
There are no dependencies or blockers for this feature.
121+
122+
## ✅ Success Criteria
123+
124+
### 10. **Definition of Done**
125+
126+
**Question**: How do we know this feature is complete and working correctly?
127+
128+
**Your Answer**:
129+
130+
- [ ] Schemars crate added as dependency
131+
- [ ] All config types derive `JsonSchema`
132+
- [ ] CLI accepts `create schema [PATH]` command
133+
- [ ] Schema prints to stdout when no path provided
134+
- [ ] Schema writes to file when path provided
135+
- [ ] `create template` output mentions schema generation
136+
- [ ] Generated schema validates example JSON files
137+
- [ ] Unit tests for schema generation
138+
- [ ] Documentation updated (user guide, commands.md)
139+
- [ ] Example IDE configuration provided (VS Code settings.json)
140+
141+
All of them.
142+
143+
### 11. **Testing Requirements**
144+
145+
**Question**: What level of testing is expected? (Unit | Integration | E2E)
146+
147+
**Your Answer**:
148+
149+
- **Unit Tests**: Test schema generation from config types
150+
- **Integration Tests**: Test CLI command with stdout and file output
151+
- **E2E Tests**: Not required - this is a utility command that doesn't affect deployment
152+
- **Manual Testing**: Verify schema validates against actual environment JSON files
153+
154+
All of them. For the E2E tests, we can follow the example of other commands like `tests/e2e/create_command.rs`.
155+
156+
## 🛡️ Risk Assessment
157+
158+
### 12. **Potential Risks**
159+
160+
**Question**: What risks or challenges should we be aware of?
161+
162+
**Your Answer**:
163+
164+
- Schemars may not handle all Rust types perfectly (enums, generics)
165+
- Schema may become out of sync if config types change
166+
- Breaking changes to config structure require schema updates
167+
- Documentation burden - users need to know how to use schema in their IDE
168+
169+
I think the main risk is that Schemars may not perfectly represent all Rust types we use in our configuration structs, especially more complex types like enums or generics. We need to test and verify the generated schema to ensure it meets our needs.
170+
171+
I'm not worry about breaking changes to config structure because the deployer app is meant to be used during some minutes while deploying an environment, so users will likely regenerate the schema as needed.
172+
173+
## 📖 Documentation Requirements
174+
175+
### 13. **Documentation Needs**
176+
177+
**Question**: What documentation should be created or updated?
178+
179+
**Your Answer**:
180+
181+
- Update `docs/user-guide/commands/create.md` with schema command
182+
- Add example `.vscode/settings.json` for VS Code users
183+
- Update `docs/console-commands.md` with new command
184+
- Add troubleshooting section for IDE integration
185+
- Include schema example in repository (e.g., `examples/environment-schema.json`)
186+
187+
Correct, all of them. But notice that the documentation about the new command should be added to `docs/user-guide/commands/create.md`. We have included the documentation for its subcommands in the same file.
188+
189+
## 🔄 Future Enhancements
190+
191+
### 14. **Follow-up Work**
192+
193+
**Question**: Are there related enhancements to consider for future iterations?
194+
195+
**Your Answer**:
196+
197+
- Auto-generate schema during build/CI and commit to repository
198+
- Provide schema URL for remote referencing (`$schema` field)
199+
- Schema validation command (separate from generation)
200+
- Support for multiple schema formats (OpenAPI, GraphQL schema)
201+
- Schema diff tool to detect breaking changes
202+
203+
That would be nice to have in the future, but out of scope for the initial implementation.
204+
205+
**Status**: ✅ All questions answered by product owner
206+
**Last Updated**: December 12, 2025

0 commit comments

Comments
 (0)