feat: Add JSON Schema generation for plugin manifests #283

yamachu · 2026-01-19T17:02:28Z

Summary

Generate JSON Schema alongside docs so VS Code + Red Hat YAML extension can validate plugin YAML manifests using $schema.
Example usage in VS Code: manifest.yaml

# yaml-language-server: $schema=schema.json#/definitions/Manifest

version: 0.0.1
type: plugin
author: yamachu
...

Note: schemas with identical names are not fully disambiguated yet (e.g., multiple Python definitions may be merged). This will need a follow-up refinement if collisions appear.

I tested ...

uv run ./dify_plugin/cli.py generate-docs
uv run ./dify_plugin/cli.py generate-docs --format json-schema

Pull Request Checklist

Thank you for your contribution! Before submitting your PR, please make sure you have completed the following checks:

Compatibility Check

I have checked whether this change affects the backward compatibility of the plugin declared in README.md
I have checked whether this change affects the forward compatibility of the plugin declared in README.md
If this change introduces a breaking change, I have discussed it with the project maintainer and specified the release version in the README.md
I have described the compatibility impact and the corresponding version number in the PR description
I have checked whether the plugin version is updated in the README.md

Available Checks

Code has passed local tests
Relevant documentation has been updated (if necessary)

…n generation

gemini-code-assist · 2026-01-19T17:02:45Z

Summary of Changes

Hello @yamachu, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the developer experience for Dify plugin authors by integrating JSON Schema generation into the existing documentation pipeline. By providing a machine-readable schema for plugin manifests, IDEs can offer real-time validation and autocompletion, thereby reducing errors and streamlining the development workflow for creating and maintaining plugin configurations.

Highlights

JSON Schema Generation: Introduced the capability to generate JSON Schema definitions for plugin manifests, enabling validation in IDEs like VS Code.
CLI Enhancements: The generate-docs command now supports --format json-schema and an optional --output argument to specify the output file.
Schema Conversion Logic: Implemented new methods in SchemaDocumentationGenerator to convert Pydantic BaseModels and Enums into their corresponding JSON Schema representations, handling types, descriptions, defaults, and constraints.
Improved Schema Descriptions: Added @docs decorators to various Enum classes across entity files to provide explicit descriptions for the generated JSON Schema.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a valuable feature for generating JSON Schemas from plugin manifests, which will greatly improve validation capabilities. The implementation is well-structured. I've provided a few suggestions in dify_plugin/core/documentation/generator.py to enhance the robustness of the schema generation, particularly around type detection for enums and handling of default values and unknown types. These changes should help prevent subtle bugs and make the generator more maintainable.

gemini-code-assist · 2026-01-19T17:04:47Z

python/dify_plugin/core/documentation/generator.py

+        if enum_values:
+            first_value = enum_values[0]
+            if isinstance(first_value, str):
+                value_type = "string"
+            elif isinstance(first_value, int):
+                value_type = "integer"
+            elif isinstance(first_value, float):
+                value_type = "number"
+            elif isinstance(first_value, bool):
+                value_type = "boolean"
+            else:
+                value_type = "string"
+        else:
+            value_type = "string"


The logic to determine the JSON schema type for an Enum only considers the type of the first enum value. This can lead to incorrect schema generation for enums with mixed value types (e.g., strings and integers).

A more robust approach is to inspect all enum values to determine the set of types present.

Suggested change

if enum_values:

first_value = enum_values[0]

if isinstance(first_value, str):

value_type = "string"

elif isinstance(first_value, int):

value_type = "integer"

elif isinstance(first_value, float):

value_type = "number"

elif isinstance(first_value, bool):

value_type = "boolean"

else:

value_type = "string"

else:

value_type = "string"

if enum_values:

json_types = set()

for value in enum_values:

if isinstance(value, str):

json_types.add("string")

elif isinstance(value, bool):

json_types.add("boolean")

elif isinstance(value, int):

json_types.add("integer")

elif isinstance(value, float):

json_types.add("number")

if not json_types:

value_type = "string" # Fallback for unsupported types

elif len(json_types) == 1:

value_type = json_types.pop()

else:

value_type = sorted(list(json_types))

else:

value_type = "string"

gemini-code-assist · 2026-01-19T17:04:47Z

python/dify_plugin/core/documentation/generator.py

+                    field_schema["description"] = description
+
+            # Handle default values
+            if field_info.default is not None and str(field_info.default) != "PydanticUndefined":


The check str(field_info.default) != "PydanticUndefined" is brittle as it relies on the string representation of an internal Pydantic object, which could change in future versions. A more robust way to check if a field has a meaningful default value is to use field_info.is_required().

Suggested change

if field_info.default is not None and str(field_info.default) != "PydanticUndefined":

if not field_info.is_required() and field_info.default is not None:

gemini-code-assist · 2026-01-19T17:04:47Z

python/dify_plugin/core/documentation/generator.py

+                schemas = [self._get_json_schema_type(arg) for arg in args]
+                return {"anyOf": schemas}
+
+        return {}


The function _get_json_schema_type returns an empty dictionary {} for any type it cannot handle. While this is a valid JSON Schema that allows any value, it can hide issues where a type is not being converted correctly. This might lead to a less strict and less useful schema than intended.

Consider raising an error for unhandled types to make the schema generation process fail-fast and ensure all types are explicitly handled.

Suggested change

return {}

raise NotImplementedError(f"Type {field_type} cannot be converted to JSON Schema.")

yamachu added 3 commits January 20, 2026 01:29

feat: add output file option and json-schema support for documentatio…

f711fd0

…n generation

feat: add documentation for parameter types

8e54634

feat: implement JSON Schema generation for Pydantic models and Enums

22985e0

gemini-code-assist bot reviewed Jan 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add JSON Schema generation for plugin manifests #283

feat: Add JSON Schema generation for plugin manifests #283

Uh oh!

yamachu commented Jan 19, 2026

Uh oh!

gemini-code-assist bot commented Jan 19, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Uh oh!

gemini-code-assist bot Jan 19, 2026

Uh oh!

gemini-code-assist bot Jan 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

-        if enum_values:
-            first_value = enum_values[0]
-            if isinstance(first_value, str):
-                value_type = "string"
-            elif isinstance(first_value, int):
-                value_type = "integer"
-            elif isinstance(first_value, float):
-                value_type = "number"
-            elif isinstance(first_value, bool):
-                value_type = "boolean"
-            else:
-                value_type = "string"
-        else:
-            value_type = "string"
+        if enum_values:
+            json_types = set()
+            for value in enum_values:
+                if isinstance(value, str):
+                    json_types.add("string")
+                elif isinstance(value, bool):
+                    json_types.add("boolean")
+                elif isinstance(value, int):
+                    json_types.add("integer")
+                elif isinstance(value, float):
+                    json_types.add("number")
+            if not json_types:
+                value_type = "string"  # Fallback for unsupported types
+            elif len(json_types) == 1:
+                value_type = json_types.pop()
+            else:
+                value_type = sorted(list(json_types))
+        else:
+            value_type = "string"

	if field_info.default is not None and str(field_info.default) != "PydanticUndefined":
	if not field_info.is_required() and field_info.default is not None:

	return {}
	raise NotImplementedError(f"Type {field_type} cannot be converted to JSON Schema.")

feat: Add JSON Schema generation for plugin manifests #283

Are you sure you want to change the base?

feat: Add JSON Schema generation for plugin manifests #283

Uh oh!

Conversation

yamachu commented Jan 19, 2026

Summary

Pull Request Checklist

Compatibility Check

Available Checks

Uh oh!

gemini-code-assist bot commented Jan 19, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant