Dify 中的 JSON Schema 标准与实战指南

JSON Schema 到底是个什么？说得直白一点，它就是一种基于 JSON 格式的声明式数据校验语言。你用它来告诉系统：我接收的 JSON 数据，必须长成什么样。好比是给数据发了一张“身份证”，规定了它该有的模样。

一、什么是 JSON Schema？

先看一个直观的例子。假设你有一个用户数据：

{ "name": "张三", "age": 25, "email": "zhang@example.com" }

那么，对应的 JSON Schema 长这样：

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "age", "email"]
}

这个 Schema 的含义很明确：数据必须是 object 类型；包含三个字段，每个字段都有各自的类型约束；age 最小值为 0；email 必须符合 email 格式；而且，这三个字段都是必填的。

那么，JSON Schema 到底能做什么？它的核心能力可以归纳为以下几点：

目前 JSON Schema 有多个版本，最主流的两个是 Draft-07（2019年）和 Draft 2020-12（最新版）。

二、Dify 中用到了哪些 JSON Schema 标准？

通过对 Dify 前后端代码的全面分析，可以发现 JSON Schema 在 Dify 中间出现在 6 大场景中，涉及 20+ 个关键文件。来看具体细节。

场景一：Chatflow Start 节点表单变量校验

这是最常用的场景——在 Chatflow 的 Start 节点中配置 json_object 类型变量，用 JSON Schema 约束用户输入。

标准版本：Draft-07（通过 jsonschema Python 库实现运行时校验）。

Schema 基本结构要求：

{
  "type": "object",
  "properties": {
    "字段名": { "type": "string", "description": "说明" }
  },
  "required": ["字段名"],
  "additionalProperties": false
}

必须满足的约束（来自 preValidateSchema 逻辑）：

• 根节点必须是 type: "object"
• 必须有 properties 字段
• required 可选，值必须是字符串数组
• additionalProperties 推荐设为 false，禁止未定义字段

测试用例覆盖（test_start_node_json_object.py）：合法 Schema 正常通过；类型不匹配（如 number 传了字符串）→ 抛出 ValueError；缺少必填字段 → 抛出 ValueError；字段缺失 → 抛出 ValueError；非法 Schema 字符串 → Pydantic 校验失败。

场景二：LLM 节点结构化输出（最完整的 UI 体系）

这是 Dify 中 JSON Schema 功能最丰富的场景，提供了完整的编辑器生态。

前端组件体系：

web/app/components/workflow/nodes/llm/components/json-schema-config-modal/
├── index.tsx                  # Modal 入口
├── json-schema-config.tsx     # 主配置面板（两种编辑模式）
├── json-importer.tsx          # 从示例 JSON 导入 Schema
├── schema-editor.tsx          # 原始 JSON Schema 编辑
├── error-message.tsx          # 错误显示
├── json-schema-generator/     # AI 生成 JSON Schema
│   ├── index.tsx
│   ├── prompt-editor.tsx
│   └── generated-result.tsx
└── visual-editor/             # 可视化编辑器（拖拽式）
    ├── index.tsx
    ├── schema-node.tsx
    ├── card.tsx
    ├── add-field.tsx
    ├── hooks.ts
    ├── store.ts
    ├── context.ts
    └── edit-card/             # 字段编辑卡片
        ├── index.tsx
        ├── actions.tsx
        ├── advanced-actions.tsx
        ├── advanced-options.tsx
        └── required-switch.tsx

标准版本：Draft-07。验证流程：JSON Schema 编辑 → JSON.parse → preValidateSchema → checkJsonSchemaDepth → validateSchemaAgainstDraft7。

验证代码（utils.ts）：

import { Validator } from 'jsonschema'
import draft07Schema from './draft-07.json'

// 使用 Draft-07 元 Schema 验证
export const draft07Validator = (schema: any) => {
  return validator.validate(schema, draft07Schema)
}

// 禁止布尔属性（Dify 自定义规则）
export const forbidBooleanProperties = (schema: any, path: string[] = []): string[] => { ... }

// 预校验：必须是 { type: "object", properties, required?, additionalProperties? }
export const preValidateSchema = (schema: any) => {
  return schemaRootObject.safeParse(schema)
}

深度限制：index.ts 中定义 JSON_SCHEMA_MAX_DEPTH = 10，防止嵌套过深。

场景三：运行时表单（运行前填写）

当工作流运行时，用户需要填写 json_object 类型变量的值，Schema 会显示为占位提示。

场景四：OpenAPI 外部调用接口

Dify 通过 OpenAPI 对外暴露应用时，会将 user_input_form 转换为 JSON Schema 供调用方参考。

标准版本：Draft 2020-12（最新版）。

# api/controllers/openapi/_input_schema.py
JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema"

类型映射表：

测试用例：test_input_schema.py。

场景五：MCP 服务

Dify 作为 MCP Server 时，将 json_object 变量的 Schema 映射到 MCP Tool 的 inputSchema 中。

文件：streamable_http.py

elif item.type == VariableEntityType.JSON_OBJECT:
  parameters[item.variable]["type"] = "object"
  if item.json_schema:
    for key in ("properties", "required", "additionalProperties"):
      if key in item.json_schema:
        parameters[item.variable][key] = item.json_schema[key]

场景六：LLM 结构化输出调用

当 LLM 支持原生结构化输出时（如 GPT-4o、Gemini），Dify 将 JSON Schema 直接传给模型。

文件：structured_output.py

class ResponseFormat(StrEnum):
  JSON_SCHEMA = "json_schema"  # 原生结构化输出模式
  JSON = "JSON"                # JSON 模式
  JSON_OBJECT = "json_object"  # JSON 对象模式别名

工具参数 Schema：tool.py 的 get_llm_parameters_json_schema() 方法，将工具参数也转为 JSON Schema 供 LLM 理解。

场景七：dify-agent 独立 Agent 系统

dify-agent 是一个独立的 Agent 系统，它也使用 JSON Schema 来约束输出。

文件：output_layer.py

from jsonschema import SchemaError
from jsonschema.exceptions import ValidationError as JsonSchemaValidationError
from jsonschema.validators import validator_for

这里使用 Python 的 jsonschema 库在运行时真正做数据校验，将 JSON Schema 包装成 Pydantic AI 的 ToolOutput，实现模型输出与 Schema 的自动匹配。

总结：六大场景的 JSON Schema 标准一览

三、如何快速将手中的 JSON 转化为 JSON Schema？

方法一：在线工具（推荐，最快）

操作示例：粘贴以下 JSON 到 jsonschema.net

{
  "name": "张三",
  "age": 25,
  "skills": ["Python", "TypeScript"],
  "address": {
    "city": "北京",
    "zip": "100000"
  }
}

自动生成：

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "skills": { "type": "array", "items": { "type": "string" } },
    "address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "zip": { "type": "string" }
      },
      "required": ["city", "zip"]
    }
  },
  "required": ["name", "age", "skills", "address"]
}

方法二：用 Dify 自带的 AI 生成器

在 LLM 节点的结构化输出配置中，Dify 内置了 AI 生成功能：

1. 点击 LLM 节点 → 输出变量 → 结构化输出
2. 点击 "AI 生成" 按钮
3. 用自然语言描述你想要的输出结构
4. 点击生成，AI 自动输出 JSON Schema

方法三：在 Dify 中使用可视化编辑器

在 LLM 节点的结构化输出中，选择可视化编辑器模式：

• 无需写任何 JSON，通过拖拽和表单填写即可构建 Schema
• 支持：添加字段、设置类型、配置必填、添加枚举值、嵌套子字段
• 适合非技术人员使用

方法四：Dify 内置的 JSON 导入功能

在 LLM 节点结构化输出的 JSON Schema 编辑器中，有一个 Import from JSON 功能：

1. 粘贴一段示例 JSON 数据
2. 系统自动推导出对应的 JSON Schema
3. 可在可视化编辑器中进一步调整

方法五：速查模板（手动编写）

简单对象模板：

{
  "type": "object",
  "properties": {
    "title": { "type": "string", "description": "标题" },
    "count": { "type": "integer", "minimum": 0, "description": "数量" },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "标签列表"
    },
    "isActive": { "type": "boolean", "description": "是否激活" }
  },
  "required": ["title", "count"],
  "additionalProperties": false
}

嵌套对象模板：

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "zip": { "type": "string" }
          },
          "required": ["city"]
        }
      },
      "required": ["name"]
    }
  },
  "required": ["user"]
}

枚举值模板：

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "active", "completed", "cancelled"],
      "description": "状态"
    }
  },
  "required": ["status"]
}

方法选择建议

四、常见问题与最佳实践

1. Chatflow 表单中 Schema 不生效？

检查是否满足以下条件：

• 在 Start 节点中配置变量类型为 json_object（不是 json）
• Schema 根节点必须是 type: "object"（不能是 type: "array"）
• 必须有 properties 字段
• 用户输入必须是 JSON 对象（不能是字符串）

2. 如何限制用户只输入特定字段？

使用 additionalProperties: false 禁止未在 properties 中定义的字段：

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "required": ["name"],
  "additionalProperties": false  // 禁止额外字段
}

3. 如何让 LLM 输出特定格式？

在 LLM 节点的结构化输出中使用 JSON Schema，Dify 会自动：

• 将 Schema 传给支持原生结构化输出的模型（GPT-4o、Gemini 等）
• 对不支持原生输出的模型，在 prompt 中注入 Schema 描述
• 运行时解析和校验 LLM 输出

4. 嵌套深度有限制吗？

有！JSON_SCHEMA_MAX_DEPTH = 10，超过 10 层嵌套会报错。

5. Draft-07 和 Draft 2020-12 有什么区别？

建议：在 Dify 内部使用时都用 Draft-07 格式，它兼容性最好且所有场景都支持。