Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Support the `openapi-3.0` target in `Schema.toStandardJSONSchemaV1`

Đang mở
  • Có gì không ổn?
#9,764 3 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@MichaelDeBoey đang làm issue này rồi.

Từ ngày 22/10/2026.

  • #9777 của @MichaelDeBoey — đang mở

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
48/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
backend-api-design

Hướng nghiên cứu

Start with packages/effect/src/internal/schema/standardSchema.ts, especially toBaseStandardJSONSchemaV1, and review JsonSchema.toDocumentDraft04 plus JsonSchema.fromSchemaOpenApi3_0 and the cited nullable handling in #9462. Check the existing tests for Standard JSON Schema targets and OpenAPI 3.0 conversion. Done means the openapi-3.0 target produces valid output, including nullable schemas and definitions, without a $schema field.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement Needs Evaluation
What is the problem this feature would solve?

The Standard JSON Schema spec names three targets: draft-07, draft-2020-12 and openapi-3.0, the last one "intended as a standardized specifier for OpenAPI 3.0 which is a superset of JSON Schema "draft-04"". Schema.toStandardJSONSchemaV1 throws for it ([email protected]):

import { Schema } from "effect"

const MaybeName = Schema.toStandardJSONSchemaV1(Schema.NullOr(Schema.String))
MaybeName["~standard"].jsonSchema.input({ target: "openapi-3.0" })

Error: Unsupported target: openapi-3.0

The spec says libraries should throw for targets they don't support, so this isn't a bug. It does mean a tool that writes OpenAPI 3.0 documents from Standard JSON Schema has to reject Effect schemas or special-case them, while other implementations accept the target. For a nullable string, a literal and an exclusive range ([email protected], [email protected] through toStandardJsonSchema from @valibot/[email protected], [email protected]):

exclusive valibot: throws Error: The "gt_value" action is not supported for OpenAPI 3.0.
exclusive zod: {"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10,"exclusiveMaximum":true}
literal sury: {"type":"string","enum":["cat"]}
literal valibot: {"enum":["cat"]}
literal zod: {"type":"string","enum":["cat"]}
nullable sury: {"type":"string","nullable":true}
nullable valibot: {"type":"string","nullable":true}
nullable zod: {"nullable":true,"type":"string"}

The target check is in toBaseStandardJSONSchemaV1:

https://github.com/Effect-TS/effect/blob/110fd22e6555b86301d2e89997386b8c4b71fad3/packages/effect/src/internal/schema/standardSchema.ts#L110

What is the feature you are proposing to solve the problem?

Add an openapi-3.0 branch to toBaseStandardJSONSchemaV1. Most of the pieces exist already:

  • JsonSchema.Dialect includes "openapi-3.0", and JsonSchema.fromSchemaOpenApi3_0 reads it.
  • JsonSchema.toDocumentDraft04 (#6883, for #6846) writes the draft-04 base that OpenAPI 3.0 extends.

https://github.com/Effect-TS/effect/blob/110fd22e6555b86301d2e89997386b8c4b71fad3/packages/effect/src/JsonSchema.ts#L58

For the same three shapes, toDocumentDraft04 already matches the output above except for null, which OpenAPI 3.0 expresses as nullable: true rather than { "type": "null" }:

import { JsonSchema, Schema } from "effect"

const shapes = {
  exclusive: Schema.Finite.check(Schema.isGreaterThan(0), Schema.isLessThan(10)),
  literal: Schema.Literal("cat"),
  nullable: Schema.NullOr(Schema.String),
}
for (const [name, schema] of Object.entries(shapes)) {
  console.log(name, JSON.stringify(JsonSchema.toDocumentDraft04(Schema.toJsonSchemaDocument(schema)).schema))
}

exclusive {"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10,"exclusiveMaximum":true}
literal {"type":"string","enum":["cat"]}
nullable {"anyOf":[{"type":"string"},{"type":"null"}]}

So the remaining work is mostly the nullable rewrite (the reverse of what fromSchemaOpenApi3_0 does, including #9462) and deciding where definitions go in a standalone schema. zod keeps them in a root definitions with #/definitions/... references for this target. OpenAPI 3.0 schema objects have no $schema, and none of the libraries above write one for this target.

For reference, Effect 3's JSONSchema.make offered jsonSchema7, jsonSchema2019-09, jsonSchema2020-12 and openApi3.1, so OpenAPI 3.0 output would be new in either major.

What alternatives have you considered?

Calling JsonSchema.toDocumentDraft04(Schema.toJsonSchemaDocument(schema)) and rewriting null branches by hand works for Effect schemas, but not for tools that consume schemas through the Standard JSON Schema interface without knowing the vendor.

Ngôn ngữ chính
TypeScript
Star
16.7k
Fork
808
Merge trung bình
11 giờ 24 phút
Pull request đã merge (30 ngày)
848

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. 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.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Effect-TS/effect

Tất cả issue của Effect-TS/effect

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.