深入理解Ajv中的JSON类型定义(JTD)规范

谢璋声Shirley

于 2025-06-03 09:00:36 发布

阅读量363

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00022/article/details/148391551

深入理解Ajv中的JSON类型定义(JTD)规范

ajv 项目地址: https://gitcode.com/gh_mirrors/ajv/ajv

JSON Type Definition (JTD) 是一种用于定义JSON数据结构的规范，作为Ajv验证器的重要组成部分，它提供了一种简洁而强大的方式来描述和验证JSON数据。本文将全面解析JTD规范在Ajv中的实现与应用。

JTD基础概念

JTD规范定义了8种不同的模式形式，用于描述JSON消息中最常用的数据类型。与JSON Schema相比，JTD具有更严格的结构和更明确的类型定义，这有助于减少用户错误并提高验证效率。

初始化JTD验证器

要使用JTD模式，需要导入特定的Ajv类：

// JavaScript
const Ajv = require("ajv/dist/jtd")
const ajv = new Ajv()

// TypeScript
import Ajv from "ajv/dist/jtd"
const ajv = new Ajv()

JTD模式形式详解

1. 类型形式（基本值）

定义基本数据类型，必须包含type成员，可选nullable和metadata。

支持的类型包括：

字符串："string"
布尔值："boolean"
时间戳："timestamp"
整数类型：int8, uint8, int16, uint16, int32, uint32
浮点数类型：float32, float64

示例：

{
  type: "string",
  nullable: true  // 允许null值
}

2. 枚举形式

定义只能取特定字符串值的枚举类型。

示例：

{
  enum: ["red", "green", "blue"]
}

3. 元素形式（数组）

定义同类型元素的数组。

示例：

{
  elements: {
    type: "uint8"
  }
}

4. 属性形式（对象）

定义具有特定属性的对象，分为必需属性和可选属性。

特点：

properties定义必需属性
optionalProperties定义可选属性
additionalProperties控制是否允许额外属性

示例：

{
  properties: {
    name: {type: "string"}
  },
  optionalProperties: {
    age: {type: "uint8"}
  },
  additionalProperties: true
}

5. 鉴别器形式（标签联合）

定义基于标签值的不同类型对象联合。

特点：

discriminator指定标签属性名
mapping定义不同标签值对应的模式

示例：

{
  discriminator: "type",
  mapping: {
    "admin": {
      properties: {
        permissions: {elements: {type: "string"}}
      }
    },
    "user": {
      properties: {
        email: {type: "string"}
      }
    }
  }
}

6. 值形式（字典）

定义值类型相同的字典对象。

示例：

{
  values: {
    type: "float32"
  }
}

7. 引用形式

引用根模式中definitions定义的子模式。

示例（二叉树结构）：

{
  definitions: {
    node: {
      properties: {
        value: {type: "int32"}
      },
      optionalProperties: {
        left: {ref: "node"},
        right: {ref: "node"}
      }
    }
  },
  ref: "node"
}

8. 空形式

允许任何类型的值，包括null。

类型安全与JTDSchemaType

TypeScript用户可以使用JTDSchemaType来确保模式与类型定义匹配：

interface User {
  id: number
  name: string
  isActive?: boolean
}

const userSchema: JTDSchemaType<User> = {
  properties: {
    id: {type: "uint32"},
    name: {type: "string"}
  },
  optionalProperties: {
    isActive: {type: "boolean"}
  }
}

对于引用模式，需要提供定义的类型作为第二个泛型参数：

const schema: JTDSchemaType<{val: number}, {num: number}> = {
  definitions: {
    num: {type: "float64"}
  },
  properties: {
    val: {ref: "num"}
  }
}