Improve 3.1+ schema `$id` UX
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 25/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Đình trệ
- Công nghệ
- json
- Lĩnh vực
- api
Hướng nghiên cứu
Bắt đầu bằng cách so sánh các định nghĩa schema và schema-base hiện có của OAS 3.1, bao gồm cách dialect/base và meta/base được tham chiếu. Được xem là hoàn tất khi một schema có tên trực quan cung cấp việc xác thực Schema Object mặc định, cho phép các tài nguyên được nhúng chuyển đổi metaschema và làm cho hành vi chưa hoàn chỉnh của schema trở nên rõ ràng hơn.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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 againsttype: [boolean, object]schema-base# Extendsschemato validate Schema Objects againstdialect/baseand require both$schemaandjsonSchemaDialectto be set toschema's$idif they are presentdialect/base# A dialect equivalent to the default 2020-12 dialect plus the OAS extensionsmeta/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.
- Ngôn ngữ chính
- Markdown
- Star
- 31.2k
- Fork
- 9.2k
- Merge trung bình
- 2 ngày 9 giờ
- Pull request đã merge (30 ngày)
- 17
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của OAI/OpenAPI-Specification
-
Housekeeping
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 45/100
OAI/OpenAPI-Specification#5566 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Housekeeping
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 35/100
OAI/OpenAPI-Specification#5562 · 4 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Housekeeping
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 10/100
OAI/OpenAPI-Specification#5556 · 3 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
v3.2.1 releaseCó thể làm lại được @lornajane đã nhận 32 ngày trước và không có pull request nào đang mở. Đang mở
OAI/OpenAPI-Specification#5460 · 11 bình luận · 1 reaction · 1 người được giao ·
Maintainer thường phản hồi trong vòng 1 ngày
-
param serialization
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 25/100
OAI/OpenAPI-Specification#5366 · 12 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của OAI/OpenAPI-Specification
Issue tương tự
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
better-auth/better-auth#11723 · 1 reaction ·
Maintainer thường phản hồi trong vòng 1 ngày
-
enhancement from-review
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
khuisman/mcp-gee-sweet#1010 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Worker-Erstellung bricht langsame Git-Worktree-Checkouts nach 20 Sekunden abCó thể đã có người làm @KajoVanBuyten đã nhận hôm nay. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 69/100
AgentSystemLabs/agent-office#367 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
area: backend bug priority: high
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 83/100
snapotter-hq/SnapOtter#2423 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
area::tern difficulty::easy good first issue kind::bug triage::ready
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100