Plugin Taxonomy and Validation#

Dify plugins declare free-form tags in their manifest.yaml. Tag checking—along with all other manifest validation—is owned by the plugin daemon, not the Dify API layer. The API passes tags through unmodified; the daemon performs the actual filtering and any content enforcement.

Tag Field in PluginDeclaration#

Tags are modeled as an unconstrained string list in PluginDeclaration:

tags: list[str] = Field(default_factory=list)

There is no StrEnum or allow-list enforced at the Pydantic level. The API controller (PluginCategoryListQuery) accepts tags from callers as a raw list and constrains only its length (max_length=128), not individual values.

The conventional tag vocabulary used by official plugins is:

A plugin may carry multiple tags (e.g., discord_trigger uses both social and utilities) 1.

Category vs. Tag#

Dify distinguishes between two classification axes:

• Category (PluginCategory) — auto-detected from the manifest's top-level provider keys (tool, model, datasource, agent_strategy, trigger). Set by a @model_validator in PluginDeclaration; plugins with no recognized provider key default to Extension. Category values: Tool, Model, Extension, AgentStrategy ("agent-strategy"), Datasource, Trigger 2.
• Tags — author-supplied, freeform strings for discovery/filtering. The API layer exposes a list_by_category endpoint that accepts tags as an additional filter 3.

Validation Architecture: Daemon-Delegated#

The Dify API never parses manifest.yaml directly. The flow is:

1. On install or upload, the plugin package is forwarded to the daemon via PluginInstaller.upload_pkg().
2. The daemon parses, validates, and stores the manifest; it returns a PluginDeclaration-shaped JSON payload.
3. The API deserializes the response with Pydantic model_validate() — the only API-layer schema enforcement that occurs.
4. For manifest retrieval, PluginInstaller.fetch_plugin_manifest() issues a GET to plugin/{tenant_id}/management/fetch/manifest and deserializes the daemon's response into a PluginDeclaration.
5. The high-level PluginService.fetch_plugin_manifest() wraps this call for all API consumers.

Because the API applies no tag allow-list, any tag value stored in the manifest by the daemon will round-trip through the API unchanged. Adding or removing accepted tags only requires a daemon change, not an API change.

Tag-Based Listing#

PluginService.list_by_category() accepts a tags: Sequence[str] parameter and forwards it verbatim to the daemon endpoint plugin/{tenant_id}/management/{category}/list 4. The daemon applies category, query, and tag filters server-side before paginating results.

Key Files#