JSON Validator、JSON Linter 和 JSON Schema 有什么区别？一篇讲清三者用途

开发中经常出现一种困惑：一段 JSON 已经能够被解析，为什么接口仍然拒绝它？或者 JSON Validator 显示有效，JSON Linter 却继续报告问题？

原因是这三类工具解决的不是同一个问题。JSON Validator 检查文本是否合法，JSON Linter 检查质量与约定，JSON Schema 描述数据必须满足的结构和规则。它们不是互相替代，而是位于同一条质量流水线的不同阶段。

如果只想快速选择，可以先看这张表。

> 最实用的顺序：先验证语法，再执行 Lint，最后使用 JSON Schema 验证业务结构。

先解决一个术语歧义：Validator 到底验证什么

“JSON Validator”在不同产品中可能指两种工具：

1. JSON 语法验证器：检查文本是否符合 JSON 语法，通常以 JSON.parse 或等价解析器为基础。

1. JSON Schema Validator：接收一份 JSON Schema 和一份 JSON Instance，再判断数据是否符合 Schema。

Json Work 当前的 JSON Validator 属于第一类，主要检查语法并定位解析错误。JSON Schema 官方文档所说的 Validator 通常属于第二类：它以 Schema 和 Instance 为输入，输出验证结果。

写文档、选工具或讨论接口时，最好明确说“syntax validator”还是“schema validator”，否则双方可能使用同一个词表达完全不同的验证层次。

第一层：JSON Validator 检查文本能不能解析

JSON 是一种具有明确语法的数据交换格式。RFC 8259规定了对象、数组、字符串、数字、布尔值和 null 等合法形式。语法验证器关心的是字符和结构是否满足这些规则。

下面的内容不是合法 JSON，因为 id 与 name 之间缺少逗号：

{
  "id": 101
  "name": "Alice"
}

语法验证器通常能够发现：

• • 对象属性或数组元素之间缺少逗号

• • 键或字符串没有使用双引号

• • 大括号、方括号或引号没有闭合

• • 字符串包含非法转义或未转义控制字符

• • 使用了 undefined、NaN、Infinity 等 JSON 不支持的值

• • 文档被截断，解析器读到末尾仍未完成结构

修复逗号后，下面的数据在语法上完全有效：

{
  "id": "one hundred",
  "email": "not-an-email",
  "active": "yes"
}

但“能够解析”不代表它符合你的接口。语法验证器不知道 id 是否应该是整数，也不知道 active 是否必须是布尔值。它只回答：这是不是合法 JSON 文本？

如果语法失败，可以先用 JSON Validator 定位错误；如果内容只是接近 JSON，再考虑 JSON Repair，并人工核对修复结果。

第二层：JSON Linter 检查质量与一致性

Lint 是基于规则的静态分析。与 JSON 语法不同，Lint 规则通常不是统一标准，而是工具或团队根据可维护性、风格和风险制定的约定。

例如：

{
  "user_id": 101,
  "userName": "Alice",
  "isActive": "true"
}

这段 JSON 语法有效，但 Linter 可能提示：

• • user_id 与 userName 使用了不同命名风格

• • isActive 看起来像布尔字段，却使用了字符串

• • 相似对象中的同一字段类型不一致

• • 嵌套层级过深或对象过大

• • 存在重复值、可疑键名或团队禁用的模式

这些提示不一定代表数据错误。"true" 也可能是上游系统明确要求的字符串，snake_case 和 camelCase 也没有绝对的优劣。Linter 的价值是让隐含约定变得可见，并帮助团队保持一致。

因此，JSON Linter更适合回答：

• • 数据是否遵循团队命名规范？

• • 是否存在可维护性或一致性风险？

• • 是否有值得人工检查的可疑结构？

它不能替代业务契约。没有 Schema 时，Linter只能根据启发式规则猜测 isActive 是否应该是布尔值。

第三层：JSON Schema 定义数据契约

JSON Schema 是一种用于描述和约束 JSON 文档的标准化词汇。它可以表达数据类型、必填字段、嵌套对象、数组元素、数值范围、字符串长度、枚举和组合条件。JSON Schema 官方介绍将其用途概括为验证、数据交换和文档化。

下面是一份用户数据 Schema：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

这份 Schema 明确表达：

• • id 必须是整数

• • name 必须是非空字符串

• • email 是字符串，并标注为 email 格式

• • active 如果存在，必须是布尔值

• • id、name、email 必须存在

• • 不接受 Schema 未声明的额外字段

需要注意，JSON Schema 是规则文档，不是执行程序。你仍然需要 AJV、Python jsonschema 等 Schema Validator，把 Schema 应用到实际 JSON Instance 上。JSON Schema 官方入门也把这两个输入区分为 Schema 与 Instance。

还要注意实现差异。例如 format 在 JSON Schema 中默认可能只是注解，是否作为强制断言取决于验证器和配置。JSON Schema 的 format 说明明确提醒了这一点。生产环境应确认所用验证器、Draft 版本和选项。

你可以使用 JSON Schema Generator从真实样本生成基础 Schema，再人工补充范围、长度、正则、枚举和 additionalProperties 等业务规则。自动推断是起点，不是业务知识的替代品。

用同一份 API 数据看懂三者

假设接口收到：

{
  "id": "101",
  "name": "Alice",
  "email": "alice@example.com",
  "active": "true"
}

JSON Validator 的结论

通过。引号、逗号和括号都正确，所有值也符合 JSON 语法。

JSON Linter 的结论

可能给出建议。id 看起来像数字，active 看起来像布尔值，Linter 可以把它们标记为可疑字符串。但没有正式契约时，它不能证明这两个值一定错误。

JSON Schema Validator 的结论

不通过。按照上一节的 Schema，id 必须是整数，active 必须是布尔值。这里的失败不是语法错误，而是契约错误。

这就是最关键的区别：

语法有效 ≠ 风格一致 ≠ 符合业务契约

一张更完整的对比表

推荐的组合工作流

在 API、配置文件或数据导入流程中，可以按下面顺序执行：

1. Syntax gate：先确认原始文本能够解析。

1. Lint gate：检查命名、一致性和团队质量规则。

1. Schema gate：使用明确版本的 Schema 验证数据契约。

1. Business gate：执行跨字段、数据库状态或权限相关的业务检查。

Schema 也不能表达所有业务逻辑。例如“结束时间必须晚于开始时间”“用户必须有权访问该项目”通常仍需要应用代码或专门规则。不要把 Schema 验证通过等同于业务操作一定安全。

在 CI/CD 中，这四层可以分别失败并给出不同信息：语法失败应立即停止；Lint 警告可以按团队策略处理；Schema 失败通常应阻止部署或数据进入下游；业务失败则需要领域相关的错误说明。

使用 AJV 执行 Schema 验证

下面是一个最小 JavaScript 示例。为了让重点保持清晰，示例只使用 type 和 required，没有引入额外的 format 插件。

import Ajv from "ajv";

const schema = {
  type: "object",
  properties: {
    id: { type: "integer" },
    name: { type: "string" },
    active: { type: "boolean" }
  },
  required: ["id", "name"],
  additionalProperties: false
};

const data = {
  id: "101",
  name: "Alice",
  active: true
};

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

if (!validate(data)) {
  console.log(validate.errors);
}

AJV 会报告 id 类型不符合 integer。其官方指南推荐复用已经编译的验证函数，而不是为每条数据重复编译同一份 Schema。AJV 入门指南

但这段代码仍假设 data 已经是 JavaScript 值。如果输入来自网络中的原始字符串，仍然需要先解析 JSON；语法错误和 Schema 错误最好分别处理，才能给使用者准确的反馈。

常见误解

“Validator 通过，数据就一定正确”

不对。语法 Validator 只证明文本可解析。即使 Schema Validator 通过，也只证明数据满足这份 Schema，不能证明 Schema 覆盖了全部业务要求。

“Linter 报警就必须修改”

不一定。Lint 规则应服务于明确的团队约定。规则不适合当前数据源时，应调整规则或记录例外，而不是机械修改数据含义。

“从一个样本生成的 Schema 就是最终契约”

不对。单个样本无法可靠推断哪些字段可选，也无法知道未来允许的范围、枚举和边界条件。应使用多个代表性样本，并由了解业务的人复核。

“JSON Schema 可以修复无效 JSON”

不能。Schema 用于描述和验证数据，不负责补逗号、修引号或恢复被截断的内容。语法无效时，应先使用 Validator 或 Repair 工具。

什么时候使用哪一个

• • 从日志复制的 JSON 无法打开：先用 JSON Validator。

• • 团队需要统一字段命名和结构习惯：使用 JSON Linter。

• • API 请求或响应必须遵循固定格式：使用 JSON Schema。

• • 第三方数据进入数据库前：依次进行语法、Schema 和业务验证。

• • 配置文件提交到仓库前：在编辑器和 CI 中组合 Validator、Linter 与 Schema。

• • 刚拿到一份没有文档的 API 样本：先生成基础 Schema，再根据更多样本和接口约定修订。

总结

JSON Validator、JSON Linter 和 JSON Schema 分别守住三条不同的边界：

• • Validator 守住合法语法

• • Linter 守住质量与一致性

• • JSON Schema 守住结构与数据契约

最可靠的方案不是从中只选一个，而是按顺序组合使用。先让文本能够被正确解析，再检查团队质量规则，最后使用经过复核的 Schema 验证真实业务约束。

你可以从 JSON Validator开始检查语法，使用 JSON Linter发现质量问题，再通过 JSON Schema Generator建立可维护的数据契约。所有这些操作都可以在浏览器本地完成。