Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Improve 3.1+ schema `$id` UX

未关闭
  • 哪里不对？
#4,147 47 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
停滞
技术栈
json
领域
api

调研方向

首先比较现有的 OAS 3.1 schema 和 schema-base 定义，包括 dialect/base 和 meta/base 的引用方式。完成的标准是：一个名称直观的 schema 提供默认的 Schema Object 验证，同时允许嵌入资源切换 metaschema，并使 schema 的不完整行为更加明显。

由索引模型根据 Issue 内容生成。

描述

Schema

Currently, we have the following schema document $ids for OAS 3.1 (shown relative to a base URI of https://https://spec.openapis.org/oas/3.1/, and without the trailing date segment that all schemas need to support updates:

  • schema # Validates everything except the Schema Object, which is only validated against type: [boolean, object]
  • schema-base # Extends schema to validate Schema Objects against dialect/base and require both $schema and jsonSchemaDialect to be set to schema's $id if they are present
  • dialect/base # A dialect equivalent to the default 2020-12 dialect plus the OAS extensions
  • meta/base # The vocabulary metaschema for the OAS extensions

schema-base was named to indicate that it incorporates dialect/base. No one is certain why the dialect and vocabulary are referred to as "base", but they are called that in the OAS text as well. I vaguely recall discussing the dialect as a base for further OAS-relevant extensions? Perhaps that is what the intent was.

AFAICT, the advantage of schema is that it's self-contained. But giving it that name means that it is the schema that most people assume is what they want, yet it really does not produce the behavior they'd expect.

schema-base is closer to what people would expect, but is (in my view) overly restrictive in locking $schema to dialect/base, as it is valid to switch metaschemas if $schema appears alongside $id, and conforming JSON Schema implementations know to treat $id-containing subschemas as embedded resources and check for a changed metaschema. However, this does not make schema-base wrong: Users might indeed want to enforce using only dialect/base, and this is the correct way to do that.

On the other hand (and contrary to some of my comments earlier on Slack), schema-base locking jsonSchemaDialect to dialect/base is probably correct. If you want to set jsonSchemaDialect to something else, you would want a schema that validates Scheam Objects accordingly by default.

We probably shouldn't change how schema behaves, but we should make it more obvious that it is incomplete. We should also come up with some sort of intuitive name for a schema that is like schema-base but does not restrict $schema. This name needs to convey that most users will want this new schema, and not the plain schema.

Ideally, I'd prefer to make copies of the vocabulary and dialect and give them the URIs dialect/oas and meta/oas (3.1 is already present earlier in the URI), but that is probably more trouble than it is worth given that I imagine very few people pay attention to those other than to just load them correctly when using schema-base.

The important thing is to have an intuitively-named schema that performs the default accepted Schema Object validation but still allows switching metaschemas on embedded resources. That is the default behavior of the OAS, and it's not currently provided.

主要语言
Markdown
星标
31.2k
派生
9.2k
平均合并
2 天 9 小时
30 天内合并 PR
17

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

OAI/OpenAPI-Specification 的其他 Issue

查看 OAI/OpenAPI-Specification 的全部 Issue

相似的 Issue

更多 Backend & API Design Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。