Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#9,764 3 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@MichaelDeBoey ya está trabajando en esto.

Desde el 22/10/2026.

  • #9777 de @MichaelDeBoey — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript
Área
backend-api-design

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
16.7k
Forks
808
Merge medio
11 h 24 min
PR fusionados (30 d)
848

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Effect-TS/effect

Todos los issues de Effect-TS/effect

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.