使用Quicktype转换含allOf的JSON Schema生成TS接口结果异常

我们正在从JSON Type Definition切换到JSON Schema，使用Quicktype工具将JSON Schema转换为TypeScript类型。大部分场景下工具表现正常，但遇到结合if-then的allOf鉴别器结构时，工具直接忽略了allOf部分，生成的TS类型缺失了关键字段。

使用的转换命令 #

quicktype -o ./src/typings.ts --just-types --acronym-style camel --src-lang schema

预期生成的TypeScript类型 #

export type CreateCustomerCommandPayloadV1 = CreateCustomerCommandPayloadV1Person | CreateCustomerCommandPayloadV1Company;

export interface CreateCustomerCommandPayloadV1Person {
    type: CreateCustomerCommandPayloadV1Type.Person;
    customerKey: string
    firstName: string
    lastName: string
}
export interface CreateCustomerCommandPayloadV1Company {
  type: CreateCustomerCommandPayloadV1Type.Company;
  customerKey: string
  companyName: string
}

export enum CreateCustomerCommandPayloadV1Type {
    Company = "COMPANY",
    Person = "PERSON",
}

实际生成的TypeScript类型 #

export interface CreateCustomerCommandPayloadV1 {
    type: CreateCustomerCommandPayloadV1Type;
}

export enum CreateCustomerCommandPayloadV1Type {
    Company = "COMPANY",
    Person = "PERSON",
}

原JSON Schema文件 #

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "metadata": {
    "description": "Command: Creates a new customer (Types: COMPANY | PERSON)",
    "subject": "commands.crm.customers.createCustomer",
    "authenticationRequired": true
  },
  "type": "object",
  "additionalProperties": false,
  "$id": "CreateCustomerCommandPayloadV1",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "COMPANY",
        "PERSON"
      ]
    },
    "customerKey": {
      "type": "string"
    }
  },
  "required": [
    "type"
  ],
  "$comment": "discriminator",
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "COMPANY"
          }
        }
      },
      "then": {
        "properties": {
          "companyName": {
            "type": "string"
          }
        },
        "required": [
          "companyName"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "PERSON"
          }
        }
      },
      "then": {
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        },
        "type": "object",
        "additionalProperties": false,
        "title": "CreateCustomerCommandPayloadV1Person",
        "required": [
          "firstName",
          "lastName"
        ]
      }
    }
  ]
}

问题原因与解决方案 #

原因 #

Quicktype对JSON Schema的if-then条件结构支持有限，更适配**oneOf结合鉴别器（discriminator）**的标准联合类型定义方式。原Schema用allOf+if-then实现的分支逻辑，Quicktype无法正确识别并转换为TS的联合类型。

修改后的JSON Schema #

将结构调整为oneOf+鉴别器的标准形式，让Quicktype能识别分支逻辑：

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "metadata": {
    "description": "Command: Creates a new customer (Types: COMPANY | PERSON)",
    "subject": "commands.crm.customers.createCustomer",
    "authenticationRequired": true
  },
  "type": "object",
  "additionalProperties": false,
  "$id": "CreateCustomerCommandPayloadV1",
  "discriminator": {
    "propertyName": "type"
  },
  "properties": {
    "type": {
      "type": "string",
      "enum": ["COMPANY", "PERSON"]
    },
    "customerKey": {
      "type": "string"
    }
  },
  "required": ["type", "customerKey"],
  "oneOf": [
    {
      "properties": {
        "type": { "const": "COMPANY" },
        "companyName": { "type": "string" }
      },
      "required": ["companyName"],
      "additionalProperties": false
    },
    {
      "properties": {
        "type": { "const": "PERSON" },
        "firstName": { "type": "string" },
        "lastName": { "type": "string" }
      },
      "required": ["firstName", "lastName"],
      "additionalProperties": false
    }
  ]
}

关键调整点 #

1. 替换allOf为oneOf，明确表示这是互斥的分支类型
2. 添加discriminator字段指定type作为鉴别器，引导Quicktype识别联合分支
3. 将customerKey加入全局required，避免在每个分支重复定义
4. 每个oneOf分支内定义专属字段和必填项

重新执行原转换命令，即可生成符合预期的TypeScript联合类型。

内容的提问来源于stack exchange，提问作者Janis-Hahn