为什么这个对象对 OpenAPI 3.0 中的两种模式都有效？答案

【问题标题】：Why is this object valid against both schemas in OpenAPI 3.0?为什么这个对象对 OpenAPI 3.0 中的两种模式都有效？
【发布时间】：2018-04-20 09:30:17
【问题描述】：

在这个doc 中，定义了两个模式：

components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer

然后文档说：

以下 JSON 对象对 both 架构有效

{
  "bark": true,
  "hunts": true,
  "breed": "Husky",
  "age": 3      
}

JSON Schema Validation 规范说：

如果对于出现在实例中以及作为该关键字值中的名称的每个名称，该名称的子实例成功地针对相应的架构进行验证，则验证成功。

如果我理解正确，这个对象对Dog 无效，因为它有一个意外的键hunts，对Cat 无效，因为它有一个意外的键bark。

为什么文档说这个对象对两种模式都有效？

【问题讨论】：

标签： openapi json-schema-validator

【解决方案1】：

OpenAPI Schema Object 支持 additionalProperties 关键字，该关键字指定在实例中是否允许未在架构中明确定义的属性。

在 OpenAPI 3.0 中，additionalProperties = true 默认情况下（与 additionalProperties: {} 相同）。这就是您示例中的实例对两种模式都有效的原因。

如果您需要禁止额外的属性，请将 additionalProperties: false 显式添加到您的架构中。

我还没有找到定义此行为的here

additionalProperties: true 作为默认值目前没有明确声明，但可以从其他声明中暗示。有一个PR 明确提及这一点。

OpenAPI 3.0.1 规范说（强调我的）：

Schema Object ... 是JSON Schema Specification Wright Draft 00 的扩展子集。 ... 除非另有说明，否则属性定义遵循 JSON Schema。

和相应的JSON Schema Validation 规范（Wright Draft 00）说：

如果“additionalProperties”不存在，它可能被认为存在一个空模式作为值。
...
如果“additionalProperties”是一个对象，则将该值验证为所有未通过“properties”或“patternProperties”验证的属性的架构。

所以 JSON Schema 中的默认值是additionalProperties: {}。并且空模式匹配任何实例，这相当于additionalProperties: true。

【讨论】：