citrusframework / citrusframework/citrus

Improve documentation quality in generated JSON Schema

Open
#1,653 0 comments 0 reactions 0 assignees View on GitHub
docs maintenance
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.