英文:
Can `required` name be missing from `properties` in the OpenAPI schema
问题
我正在阅读OpenAPI v3.1规范，并尝试查找关于可以为请求体的媒体类型定义的required字段的任何信息。从示例中清楚地显示，如果required包含一个properties项的名称，那么该项是必需的。
但是，有些情况（我想）type: object的properties字段可以被省略，这意味着可以接受具有任意字段的object。
我想，对于type: object，如果未指定properties字段，则不允许指定包含名称的required列表。但我找不到明确说明不允许的摘录。
因此，问题是：
OpenAPI规范是否允许在required中提到一个在properties中未提及的属性名称，或者当未定义properties字段时是否允许？
示例1：
required:
- name
- age
# 未指定
# properties:
示例2：
properties:
- name
# `age`在属性中缺失
required:
- name
- age
更新
根据json-schema.org：
> 如果对象实例的属性集包含此关键字的数组值中的所有元素，则该关键字是有效的。[重点添加]
严格来说，似乎是允许的...
英文:
I am reading the OpenAPI v3.1 specification and trying to find any info regarding the required field that can be defined for a media type for a request's body. From the examples it is clear that if required contains a name of an properties item, the item is required.
However, there are cases (I suppose), where properties field can be omitted for type: object, meaning that an object with arbitrary fields can be accepted.
I suppose that for a type: object where the properties field is not specified it is not allowed to specify a required list with names. But I can't find an excerpt that would explicitly state that it is not allowed.
Hence, the question:
Is it allowed by an OpenAPI specification to mention a property name in required that is not mentioned in the properties or when the properties field is not defined?
Example 1:
required:
- name
- age
# not specified
# properties:
Example 2:
properties:
- name
# `age` is missing from the properties
required:
- name
- age
UPDATE
According to json-schema.org:
> An object instance is valid against this keyword if its property set contains all elements in this keyword's array value. [emphasis added]
Strictly speaking, it seems to be allowed...
答案1
得分: 1
规范本身并不是非常严格的，但如果您使用了代码检查或验证工具，且存在未定义的必需属性，我会期望该工具会通知您存在问题。
英文:
The specification itself isn't very restrictive, but if you use a linting or validation tool and there's a required property that isn't defined, I'd expect the tool to let you know there's a problem.
答案2
得分: 1
可以。此行为源自JSON Schema，其中每个关键字都是一个独立的约束，与其他约束分开评估。
基本上，这个模式：
type: object
required:
- foo
等同于：
type: object
required:
- foo
properties:
foo: {} # 或在OAS 3.1+中为 foo: true
这意味着属性 foo 必须存在，无论其值如何（即可以具有任何值）。
但正如 @Lorna 指出的，一些API供应商和工具供应商认为在 properties 中明确定义所有已知属性是一个良好的做法。因此，取决于您使用的工具，未在 properties 中明确定义的必需属性可能会被标记为警告/错误，即使它在技术上是有效的OpenAPI。
英文:
> Is it allowed by an OpenAPI specification to mention a property name in required that is not mentioned in the properties or when the properties field is not defined?
Yes. This behavior comes from JSON Schema, where each keyword is a standalone constraint that is evaluated separately from other constraints.
Basically, this schema:
type: object
required:
- foo
is equivalent to:
type: object
required:
- foo
properties:
foo: {} # or foo: true in OAS 3.1+
and means the property foo must be present, regardless of its value (i.e. it can have any value).
<br/>
But as @Lorna noted, some API vendors and tooling vendors consider it a good practice to explicitly define all known properties in properties. So depending on the tools that you use, required properties that aren't explicitly defined may be flagged as warnings/errors, even if it's technically valid OpenAPI.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论