You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

OpenAPI 3.0如何定义可为空或非空时含至少两个必填字段的对象

你的实现不完全符合需求,存在两处核心疏漏:

  1. 缺失必填字段声明
    当前你只定义了name、additional_info的结构,但没有把这两个字段加入required数组,这意味着缺失这两个字段的请求数据也会通过校验,和你的设计预期不符。
  2. 允许额外字段的逻辑可以更严谨
    虽然JSON Schema默认additionalProperties为true,但你需要的是additional_info非空时允许任意可选键,建议显式声明,避免部分校验器的严格模式出现异常。

另外你当前的oneOf分支互斥逻辑是对的:一个分支要求additional_info必须带scheme、source,另一个分支要求additional_info不能有任何属性(只能是空对象),二者不会出现同时匹配的情况。

修正后的参考Schema如下:

model:
  description: ''
  content:
    application/json:
      schema:
        type: object
        required: # 新增必填字段声明
          - name
          - additional_info
        properties:
          name:
            type: string
        allOf:
          - oneOf:
              - type: object
                properties:
                  additional_info:
                    type: object
                    required:
                      - scheme
                      - source
                    properties:
                      scheme:
                        type: object
                        required:
                          - id
                        properties:
                          id:
                            type: integer
                      source:
                        type: string
                    additionalProperties: true # 显式声明允许任意额外字段
              - type: object
                properties:
                  additional_info:
                    type: object
                    additionalProperties: false
      examples:
        example-1:
          name: John Doe
          additional_info:
            scheme:
              id: 1
            source: direct
        example-2:
          name: John Doe
          additional_info: {}
        example-3:
          name: John Doe
          additional_info:
            scheme:
              id: 1
            source: direct
            optional_key: something

内容的提问来源于stack exchange,提问作者fallincode

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.09.29 20:18:01