NodeJS中Ajv无法定义含数组的TypeScript循环结构问题

问题现象 #

在Node.js环境使用Ajv时，仅包含parent字段的简单循环TypeScript结构可以正常定义，但一旦添加children数组类型的循环字段，取消注释相关代码后就会触发类型不兼容错误：

类型'{ type: "object"; properties: { ... }; required: ["name"]; }'无法赋值给'UncheckedJSONSchemaType<MyType, false>'

核心原因 #

报错的根源在于children数组的items属性里只使用了$ref来引用自身结构，缺少Ajv TypeScript类型校验要求的必填type属性。Ajv的类型系统需要明确知道数组元素的类型，仅靠引用无法满足类型检查的要求。

解决办法 #

给循环引用的字段（包括parent和children.items）补充明确的type声明，确保符合UncheckedJSONSchemaType的类型约束。

错误代码示例

import Ajv from "ajv";

type MyType = {
  name: string;
  parent?: MyType;
  // children?: MyType[]; // 取消注释后触发报错
};

const ajv = new Ajv();
const schema = {
  type: "object",
  properties: {
    name: { type: "string" },
    parent: { $ref: "#" },
    // children: { type: "array", items: { $ref: "#" } }, // 仅用$ref导致类型校验失败
  },
  required: ["name"],
} as const;

const validate = ajv.compile<MyType>(schema);

修正后的代码

import Ajv from "ajv";

type MyType = {
  name: string;
  parent?: MyType;
  children?: MyType[];
};

const ajv = new Ajv();
const schema = {
  type: "object",
  $id: "#MyType", // 可选，给结构设置明确ID让引用更清晰
  properties: {
    name: { type: "string" },
    parent: { type: "object", $ref: "#MyType" }, // 补充type: "object"
    children: {
      type: "array",
      items: { type: "object", $ref: "#MyType" }, // 给items添加type属性
    },
  },
  required: ["name"],
} as const;

const validate = ajv.compile<MyType>(schema);

说明 #

通过给循环引用的对象字段明确指定type: "object"，让Ajv的TypeScript类型系统能正确识别结构的循环关系，同时满足UncheckedJSONSchemaType的校验要求，即可解决类型不兼容的报错问题。

内容的提问来源于stack exchange，提问作者J. McNerney