OpenAPI中的'required'到底是什么意思？

Question

鉴于以下OpenAPI定义

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string

以下哪些对象是有效的？只有A还是A和B都有效？

A. {"id": ""}
B. {"id": null}
C. {}

这归结为一个问题，即“required = true”是指“非空的值”还是“必须存在的属性”。

https://json-schema-validator.herokuapp.com/上的JSON模式验证器表示2.无效，因为null不满足type: string约束。请注意，它不是因为id为null而抱怨，而是因为null不是字符串。但是，这对于OpenAPI / Swagger有多重要？

- Marcel Stör

Answer 1

在 OpenAPI Schema 对象中，required 关键字源自于 JSON Schema ，意思是：

如果[<code>required</code>] 数组中的每个项都是实例中属性的名称，则对象实例符合此关键字。

换句话说，required 意味着"属性必须存在"，而不管其值如何。属性值的 type、format 等是单独评估的约束条件，与 required 分开，但作为组合模式一起评估。

在您的示例中：

1. {"id": ""} 是有效的：

   • ✓ 符合 required
   • ✓ 值 "" 符合 type: string

2. {"id": null} 是无效的：

   • ✓ 符合 required
   • ✗ null 不符合 type: string（有关 null 的说明，请参见下面的注释）

3. {} 是无效的：

   • ✗ 不符合 required

请注意，OpenAPI 2.0不支持'null'类型，但在OpenAPI 3.1中得到支持，而3.0有nullable来处理空值。因此，{"id": null}符合此OpenAPI 3模式的要求：

Person:
  required:
    - id
  type: object
  properties:
    id:
      # OAS 3.1
      type: [string, 'null']

      # OAS 3.0
      # type: string
      # nullable: true

- Helen

---

非常好的答案，谢谢。并不是你的错，JSON模式规范与JavaScript/JSON中的“null”概念不太一致。 - Marcel Stör

@MarcelStör，JSON Schema确实有null类型，可将可空模式定义为{"type": ["string", "null"]}。但OpenAPI不支持type: null，而是使用nullable属性。 - Helen

这对补丁请求有什么影响？我想到任何属性都可能存在，但不一定需要，因为它是一个补丁。这是否意味着我需要为补丁和发布使用两个模型？发布需要全部，但补丁几乎什么都不需要？ - The Fool

@TheFool 在这种情况下，您需要 2 个模型。POST 模型可以是 PATCH 模型的 allOf + required 列表。示例 - Helen