Improve JsonSchema for autocompletion

[christiangoerdes]

Summary by CodeRabbit

• New Features

  • Generated JSON schemas now include human-friendly titles for top-level, child and variant objects and add explicit component reference entries.
  • Schema objects can express min/max property counts and top-level objects now require at least one property when present.

• Refactor

  • Schema generation logic streamlined for clearer naming and simpler condition handling.

• Tests

  • Tests updated to reflect the stricter top-level property validation message.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[christiangoerdes]

/ok-to-test

[coderabbitai]

Walkthrough

Adds schema title support, min/max property constraints, and componentRef entries; updates JsonSchemaGenerator to set titles, enforce single top-level property when present, adjust component variant naming, and tighten imports and conditionals.

Changes

Cohort / File(s)	Change Summary
Schema base: title support annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/AbstractSchema.java	Added protected title field, fluent setter public T title(String title), and serialize "title" in json(ObjectNode) when non-null/non-blank.
Schema model: min/max properties annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/SchemaObject.java	Added minProperties and maxProperties Integer fields with fluent setters minProperties(int) / maxProperties(int) and conditional serialization of minProperties/maxProperties in json(...).
Schema imports cleanup annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/Schema.java	Replaced wildcard/large imports with explicit imports (narrowed Jackson and java.util imports). No behavioral changes.
Generator: title, top-level constraints, components annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java	Replaced wildcard imports with explicit/static imports; sets .title(...) on top-level properties and children; enforces .minProperties(1).maxProperties(1) for single top-level object; introduces componentRef entries; adjusts variant naming and property referencing for components; removes some $ref required flags and inlines/simplifies conditionals.
Tests annot/src/test/java/com/predic8/membrane/annot/YAMLComponentsParsingTest.java	Updated expected error message to reflect new minProperties-based validation text.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay attention to AbstractSchema.title serialization and public API impact.
• Validate SchemaObject.minProperties/maxProperties integration and existing callers.
• Carefully review JsonSchemaGenerator changes: top-level property loop, .title(...) placements, .minProperties(1).maxProperties(1) semantics, componentRef construction, and variant property key/name changes.
• Ensure tests updated for error-message differences and that imports/staticmethods compile.

Possibly related PRs

• Improve yaml schema error #2383 — Modifies SchemaObject.property(...) behavior; likely interacts with the new SchemaObject fields and serialization.
• extend JsonSchemaGenerator (bean WIP) #2330 — Related changes to JSON schema generation and top-level schema handling; overlaps with generator edits here.

Suggested labels

7.x

Suggested reviewers

• rrayst

Poem

🐰
Titles hop upon the trees of schema,
Small names tucked in each JSON lemma.
Min and max keep gardens neat,
Component refs make pathways meet.
I nibble code and leave a joyful beat. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Title check	❓ Inconclusive	The title 'Improve JsonSchema for autocompletion' is partially related to the changeset. While the PR adds support for 'title' in JSON schema generation (which could support autocompletion), the title is vague and doesn't specifically describe that this PR adds title field support to schema objects.	Consider a more specific title like 'Add title field support to JSON schema objects' or 'Add title and minProperties/maxProperties to schema generation' to better reflect the primary changes.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch mem-schema-enhancement

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[membrane-ci-server]

This pull request needs "/ok-to-test" from an authorized committer.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/SchemaObject.java (1)

177-179: Consider adding validation for non-negative values.

Per JSON Schema specification, minProperties and maxProperties must be non-negative integers. Currently, callers could pass negative values. This is a minor concern since the callers are internal generator code, but a defensive check could prevent subtle bugs.

🔎 Proposed defensive validation

-    public SchemaObject minProperties(int n) { this.minProperties = n; return this; }
-    public SchemaObject maxProperties(int n) { this.maxProperties = n; return this; }
+    public SchemaObject minProperties(int n) {
+        if (n < 0) throw new IllegalArgumentException("minProperties must be non-negative");
+        this.minProperties = n;
+        return this;
+    }
+
+    public SchemaObject maxProperties(int n) {
+        if (n < 0) throw new IllegalArgumentException("maxProperties must be non-negative");
+        this.maxProperties = n;
+        return this;
+    }

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9292be6 and 25cc363.

📒 Files selected for processing (2)

• annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java (5 hunks)
• annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/SchemaObject.java (3 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-10-23T13:04:11.388Z

Learnt from: predic8
Repo: membrane/api-gateway PR: 2240
File: annot/src/main/java/com/predic8/membrane/annot/generator/JsonSchemaGenerator.java:210-215
Timestamp: 2025-10-23T13:04:11.388Z
Learning: In JsonSchemaGenerator.java, when allowForeign is true for non-list child elements, use a property named "ref" (not "$ref") with type "string" to provide IDE completion hints for Spring bean references while avoiding JSON Schema keyword collision.

Applied to files:

• annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/SchemaObject.java

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Automated tests
• GitHub Check: Analyze (java)

🔇 Additional comments (2)

annot/src/main/java/com/predic8/membrane/annot/generator/kubernetes/model/SchemaObject.java (2)

34-36: LGTM!

Using Integer (boxed type) is the right choice here since it allows null-checking to conditionally omit these properties from the generated JSON when not set.

---

53-55: LGTM!

The null-guarded serialization correctly emits minProperties and maxProperties only when explicitly set, following the existing patterns in this class.