citrusframework / citrusframework/citrus
Improve documentation quality in generated JSON Schema
- Dominant language
- Java
- Stars
- 485
- Forks
- 155
- Avg merge
- 4d 22h
- Merged PRs (30d)
- 6
Description
## Description
Extracted from #1609 (section "3. Documentation Quality"). The generated `citrus-testcase.json` schema has several documentation quality issues that affect IDE autocompletion hints, developer experience, and schema readability.
## Tasks
- [ ] **3.1 All 28 definitions lack top-level descriptions**
None of the entries in `definitions` have a `description` at the definition level.
- [ ] **3.2 Inconsistent trailing periods (120 of 1814 descriptions lack trailing period)**
- [ ] **3.3 `Element` definition properties (Selenium) have titles but no descriptions**
- [ ] **3.4 `selenium.javaScript.argument` has no `type` constraint**
- [ ] **3.5 Opaque definition names: `Expression-1`, `Expression-2`**
Different expression types distinguished only by a numeric suffix. Better: `PathValueExpression` / `PathExpression`.
- [ ] **3.6 Redundant title/description on array items**
Array items repeat parent metadata verbatim.
## Related
Parent epic: #1609
Contributor guide
Research direction
Start with the generated citrus-testcase.json schema and inspect its definitions, Element properties, selenium.javaScript.argument, and Expression-1/Expression-2 entries. Read parent issue #1609 for the broader context, then address the six listed documentation and schema-quality tasks; the work is done when those inconsistencies and omissions are resolved throughout the generated schema.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, json
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100