filter non-JSON values from schema examples and defaults, closes #5884 (#5888)

Author: gcanti

.changeset/cool-insects-move.md

@@ -0,0 +1,9 @@
+---
+"effect": patch
+---
+
+filter non-JSON values from schema examples and defaults, closes #5884
+
+Introduce JsonValue type and update JsonSchemaAnnotations to use it for
+type safety. Add validation to filter invalid values (BigInt, cyclic refs)
+from examples and defaults, preventing infinite recursion on cycles.

packages/effect/src/JSONSchema.ts

@@ -12,15 +12,17 @@ import * as Record from "./Record.js"
 import type * as Schema from "./Schema.js"
 import * as AST from "./SchemaAST.js"
 
+type JsonValue = string | number | boolean | null | Array<JsonValue> | { [key: string]: JsonValue }
+
 /**
  * @category model
  * @since 3.10.0
  */
 export interface JsonSchemaAnnotations {
   title?: string
   description?: string
-  default?: unknown
-  examples?: Array<unknown>
+  default?: JsonValue
+  examples?: Array<JsonValue>
 }
 
 /**
@@ -415,9 +417,9 @@ function getRawExamples(annotated: AST.Annotated | undefined): ReadonlyArray<unk
   if (annotated !== undefined) return Option.getOrUndefined(AST.getExamplesAnnotation(annotated))
 }
 
-function encodeExamples(ast: AST.AST, examples: ReadonlyArray<unknown>): Array<unknown> | undefined {
+function encodeExamples(ast: AST.AST, examples: ReadonlyArray<unknown>): Array<JsonValue> | undefined {
   const getOption = ParseResult.getOption(ast, false)
-  const out = Arr.filterMap(examples, (e) => getOption(e))
+  const out = Arr.filterMap(examples, (e) => getOption(e).pipe(Option.filter(isJsonValue)))
   return out.length > 0 ? out : undefined
 }
 
@@ -435,6 +437,38 @@ function filterBuiltIn(ast: AST.AST, annotation: string | undefined, key: symbol
   return annotation
 }
 
+function isJsonValue(value: unknown, visited: Set<unknown> = new Set()): value is JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return true
+  }
+  if (Array.isArray(value) || typeof value === "object") {
+    // Check for cyclic references
+    if (visited.has(value)) {
+      return false
+    }
+    visited.add(value)
+    try {
+      if (Array.isArray(value)) {
+        return value.every((item) => isJsonValue(item, visited))
+      }
+      // Exclude non-plain objects (Date, RegExp, etc.) by checking constructor
+      const proto = Object.getPrototypeOf(value)
+      if (proto !== null && proto !== Object.prototype) {
+        return false
+      }
+      // JSON only allows string keys, so exclude objects with Symbol keys
+      if (Object.getOwnPropertySymbols(value).length > 0) {
+        return false
+      }
+      // Check all values are JSON values
+      return Object.values(value).every((v) => isJsonValue(v, visited))
+    } finally {
+      visited.delete(value)
+    }
+  }
+  return false
+}
+
 function pruneJsonSchemaAnnotations(
   ast: AST.AST,
   description: string | undefined,
@@ -447,7 +481,7 @@ function pruneJsonSchemaAnnotations(
   if (title !== undefined) out.title = title
   if (Option.isSome(def)) {
     const o = encodeDefault(ast, def.value)
-    if (Option.isSome(o)) {
+    if (Option.isSome(o) && isJsonValue(o.value)) {
       out.default = o.value
     }
   }
@@ -949,7 +983,9 @@ function go(
                   if (Predicate.isString(toProperty.title)) annotations.title = toProperty.title
                   if (Predicate.isString(toProperty.description)) annotations.description = toProperty.description
                   if (Array.isArray(toProperty.examples)) annotations.examples = toProperty.examples
-                  if (Object.hasOwn(toProperty, "default")) annotations.default = toProperty.default
+                  if (Object.hasOwn(toProperty, "default") && toProperty.default !== undefined) {
+                    annotations.default = toProperty.default
+                  }
                   from.properties[fromKey] = addAnnotations(fromProperty, annotations)
                 }
               }

packages/effect/test/Schema/JSONSchema.test.ts

@@ -670,6 +670,16 @@ describe("fromAST", () => {
 })
 
 describe("make", () => {
+  it("should filter out non-JSON values and cyclic references from default and examples", () => {
+    const cyclic: any = { value: "test" }
+    cyclic.self = cyclic
+    const schema = Schema.String.annotations({ default: 1n as any, examples: ["a", 1n as any, cyclic, "b"] })
+    expectJSONSchemaAnnotations(schema, {
+      "type": "string",
+      "examples": ["a", "b"]
+    })
+  })
+
   it("handling of a top level `parseJson` should targeting the \"to\" side", () => {
     const schema = Schema.parseJson(Schema.Struct({
       a: Schema.parseJson(Schema.NumberFromString)