Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#9,764 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@MichaelDeBoey ci sta già lavorando.

Dal 22/10/2026.

  • #9777 di @MichaelDeBoey — aperta

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
backend-api-design

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

wontfix
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.

Lingua principale
TypeScript
Stelle
16.7k
Fork
808
Merge medio
12h 7m
PR unite (30g)
844

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Effect-TS/effect

Tutte le issue di Effect-TS/effect

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.