effect 3.11.4 → 3.11.5

package/src/JSONSchema.ts

@@ -20,6 +20,15 @@ export interface JsonSchemaAnnotations {
   examples?: Array<unknown>
 }
 
+/**
+ * @category model
+ * @since 3.11.5
+ */
+export interface JsonSchema7Never extends JsonSchemaAnnotations {
+  $id: "/schemas/never"
+  not: {}
+}
+
 /**
  * @category model
  * @since 3.10.0
@@ -86,6 +95,12 @@ export interface JsonSchema7String extends JsonSchemaAnnotations {
   maxLength?: number
   pattern?: string
   format?: string
+  contentMediaType?: string
+  allOf?: Array<{
+    minLength?: number
+    maxLength?: number
+    pattern?: string
+  }>
 }
 
 /**
@@ -97,6 +112,14 @@ export interface JsonSchema7Numeric extends JsonSchemaAnnotations {
   exclusiveMinimum?: number
   maximum?: number
   exclusiveMaximum?: number
+  multipleOf?: number
+  allOf?: Array<{
+    minimum?: number
+    exclusiveMinimum?: number
+    maximum?: number
+    exclusiveMaximum?: number
+    multipleOf?: number
+  }>
 }
 
 /**
@@ -181,6 +204,7 @@ export interface JsonSchema7Object extends JsonSchemaAnnotations {
  * @since 3.10.0
  */
 export type JsonSchema7 =
+  | JsonSchema7Never
   | JsonSchema7Any
   | JsonSchema7Unknown
   | JsonSchema7Void
@@ -211,31 +235,84 @@ export type JsonSchema7Root = JsonSchema7 & {
  * @since 3.10.0
  */
 export const make = <A, I, R>(schema: Schema.Schema<A, I, R>): JsonSchema7Root => {
-  const $defs: Record<string, any> = {}
-  const jsonSchema = go(schema.ast, $defs, true, [])
-  const out: JsonSchema7Root = {
-    $schema,
-    ...jsonSchema
-  }
-  // clean up self-referencing entries
-  for (const id in $defs) {
-    if ($defs[id]["$ref"] === get$ref(id)) {
-      delete $defs[id]
-    }
-  }
-  if (!Record.isEmptyRecord($defs)) {
-    out.$defs = $defs
+  const definitions: Record<string, any> = {}
+  const ast = AST.isTransformation(schema.ast) && isParseJsonTransformation(schema.ast.from)
+    // Special case top level `parseJson` transformations
+    ? schema.ast.to
+    : schema.ast
+  const out: JsonSchema7Root = fromAST(ast, {
+    definitions
+  })
+  out.$schema = $schema
+  if (!Record.isEmptyRecord(definitions)) {
+    out.$defs = definitions
   }
   return out
 }
 
-const anyJsonSchema: JsonSchema7 = { $id: "/schemas/any" }
+type Target = "jsonSchema7" | "jsonSchema2019-09" | "openApi3.1"
+
+type TopLevelReferenceStrategy = "skip" | "keep"
+
+/**
+ * Returns a JSON Schema with additional options and definitions.
+ *
+ * **Warning**
+ *
+ * This function is experimental and subject to change.
+ *
+ * **Details**
+ *
+ * - `definitions`: A record of definitions that are included in the schema.
+ * - `definitionPath`: The path to the definitions within the schema (defaults
+ *   to "#/$defs/").
+ * - `target`: Which spec to target. Possible values are:
+ *   - `'jsonSchema7'`: JSON Schema draft-07 (default behavior).
+ *   - `'jsonSchema2019-09'`: JSON Schema draft-2019-09.
+ *   - `'openApi3.1'`: OpenAPI 3.1.
+ * - `topLevelReferenceStrategy`: Controls the handling of the top-level
+ *   reference. Possible values are:
+ *   - `"keep"`: Keep the top-level reference (default behavior).
+ *   - `"skip"`: Skip the top-level reference.
+ *
+ * @category encoding
+ * @since 3.11.5
+ * @experimental
+ */
+export const fromAST = (ast: AST.AST, options: {
+  readonly definitions: Record<string, JsonSchema7>
+  readonly definitionPath?: string
+  readonly target?: Target
+  readonly topLevelReferenceStrategy?: TopLevelReferenceStrategy
+}): JsonSchema7 => {
+  const definitionPath = options.definitionPath ?? "#/$defs/"
+  const getRef = (id: string) => definitionPath + id
+  const target: Target = options.target ?? "jsonSchema7"
+  const handleIdentifier = options.topLevelReferenceStrategy !== "skip"
+  return go(ast, options.definitions, handleIdentifier, [], {
+    getRef,
+    target
+  })
+}
+
+const constNever: JsonSchema7 = {
+  "$id": "/schemas/never",
+  "not": {}
+}
+
+const constAny: JsonSchema7 = {
+  "$id": "/schemas/any"
+}
 
-const unknownJsonSchema: JsonSchema7 = { $id: "/schemas/unknown" }
+const constUnknown: JsonSchema7 = {
+  "$id": "/schemas/unknown"
+}
 
-const voidJsonSchema: JsonSchema7 = { $id: "/schemas/void" }
+const constVoid: JsonSchema7 = {
+  "$id": "/schemas/void"
+}
 
-const objectJsonSchema: JsonSchema7 = {
+const constAnyObject: JsonSchema7 = {
   "$id": "/schemas/object",
   "anyOf": [
     { "type": "object" },
@@ -243,13 +320,13 @@ const objectJsonSchema: JsonSchema7 = {
   ]
 }
 
-const empty = (): JsonSchema7 => ({
+const constEmpty: JsonSchema7 = {
   "$id": "/schemas/{}",
   "anyOf": [
     { "type": "object" },
     { "type": "array" }
   ]
-})
+}
 
 const $schema = "http://json-schema.org/draft-07/schema#"
 
@@ -291,35 +368,31 @@ const getASTJsonSchemaAnnotations = (ast: AST.AST): JsonSchemaAnnotations => {
 const pruneUndefinedFromPropertySignature = (ast: AST.AST): AST.AST | undefined => {
   if (Option.isNone(AST.getJSONSchemaAnnotation(ast))) {
     switch (ast._tag) {
+      case "UndefinedKeyword":
+        return AST.neverKeyword
       case "Union": {
-        const types = ast.types.filter((type) => !AST.isUndefinedKeyword(type))
-        if (types.length < ast.types.length) {
-          return AST.Union.make(types, ast.annotations)
+        const types: Array<AST.AST> = []
+        let hasUndefined = false
+        for (const type of ast.types) {
+          const pruned = pruneUndefinedFromPropertySignature(type)
+          if (pruned) {
+            hasUndefined = true
+            if (!AST.isNeverKeyword(pruned)) {
+              types.push(pruned)
+            }
+          } else {
+            types.push(type)
+          }
+        }
+        if (hasUndefined) {
+          return AST.Union.make(types)
         }
         break
       }
+      case "Suspend":
+        return pruneUndefinedFromPropertySignature(ast.f())
       case "Transformation":
-        return pruneUndefinedFromPropertySignature(isParseJsonTransformation(ast.from) ? ast.to : ast.from)
-    }
-  }
-}
-
-/** @internal */
-export const DEFINITION_PREFIX = "#/$defs/"
-
-const get$ref = (id: string): string => `${DEFINITION_PREFIX}${id}`
-
-const getRefinementInnerTransformation = (ast: AST.Refinement): AST.AST | undefined => {
-  switch (ast.from._tag) {
-    case "Transformation":
-      return ast.from
-    case "Refinement":
-      return getRefinementInnerTransformation(ast.from)
-    case "Suspend": {
-      const from = ast.from.f()
-      if (AST.isRefinement(from)) {
-        return getRefinementInnerTransformation(from)
-      }
+        return pruneUndefinedFromPropertySignature(ast.from)
     }
   }
 }
@@ -327,63 +400,86 @@ const getRefinementInnerTransformation = (ast: AST.Refinement): AST.AST | undefi
 const isParseJsonTransformation = (ast: AST.AST): boolean =>
   ast.annotations[AST.SchemaIdAnnotationId] === AST.ParseJsonSchemaId
 
-function merge(a: JsonSchemaAnnotations, b: JsonSchema7): JsonSchema7
-function merge(a: JsonSchema7, b: JsonSchemaAnnotations): JsonSchema7
-function merge(a: JsonSchema7, b: JsonSchema7): JsonSchema7
-function merge(a: object, b: object): object {
-  return { ...a, ...b }
-}
-
 const isOverrideAnnotation = (jsonSchema: JsonSchema7): boolean => {
   return ("type" in jsonSchema) || ("oneOf" in jsonSchema) || ("anyOf" in jsonSchema) || ("const" in jsonSchema) ||
     ("enum" in jsonSchema) || ("$ref" in jsonSchema)
 }
 
+// Returns true if the schema is an enum with no other properties.
+// This is used to merge enums together.
+const isEnumOnly = (schema: JsonSchema7): schema is JsonSchema7Enum =>
+  "enum" in schema && Object.keys(schema).length === 1
+
+const mergeRefinements = (from: any, jsonSchema: any, annotations: any): any => {
+  const out: any = { ...from, ...annotations, ...jsonSchema }
+  out.allOf ??= []
+
+  const handle = (name: string, filter: (i: any) => boolean) => {
+    if (name in jsonSchema && name in from) {
+      out.allOf.unshift({ [name]: from[name] })
+      out.allOf = out.allOf.filter(filter)
+    }
+  }
+
+  handle("minLength", (i) => i.minLength > jsonSchema.minLength)
+  handle("maxLength", (i) => i.maxLength < jsonSchema.maxLength)
+  handle("pattern", (i) => i.pattern !== jsonSchema.pattern)
+  handle("minItems", (i) => i.minItems > jsonSchema.minItems)
+  handle("maxItems", (i) => i.maxItems < jsonSchema.maxItems)
+  handle("minimum", (i) => i.minimum > jsonSchema.minimum)
+  handle("maximum", (i) => i.maximum < jsonSchema.maximum)
+  handle("exclusiveMinimum", (i) => i.exclusiveMinimum > jsonSchema.exclusiveMinimum)
+  handle("exclusiveMaximum", (i) => i.exclusiveMaximum < jsonSchema.exclusiveMaximum)
+  handle("multipleOf", (i) => i.multipleOf !== jsonSchema.multipleOf)
+
+  if (out.allOf.length === 0) {
+    delete out.allOf
+  }
+  return out
+}
+
 const go = (
   ast: AST.AST,
   $defs: Record<string, JsonSchema7>,
   handleIdentifier: boolean,
-  path: ReadonlyArray<PropertyKey>
+  path: ReadonlyArray<PropertyKey>,
+  options: {
+    readonly getRef: (id: string) => string
+    readonly target: Target
+  }
 ): JsonSchema7 => {
+  if (handleIdentifier) {
+    const identifier = AST.getJSONIdentifier(ast)
+    if (Option.isSome(identifier)) {
+      const id = identifier.value
+      const out = { $ref: options.getRef(id) }
+      if (!Record.has($defs, id)) {
+        $defs[id] = out
+        $defs[id] = go(ast, $defs, false, path, options)
+      }
+      return out
+    }
+  }
   const hook = AST.getJSONSchemaAnnotation(ast)
   if (Option.isSome(hook)) {
     const handler = hook.value as JsonSchema7
     if (AST.isRefinement(ast)) {
-      const t = getRefinementInnerTransformation(ast)
+      const t = AST.getTransformationFrom(ast)
       if (t === undefined) {
-        try {
-          return {
-            ...go(ast.from, $defs, true, path),
-            ...getJsonSchemaAnnotations(ast),
-            ...handler
-          }
-        } catch (e) {
-          return {
-            ...getJsonSchemaAnnotations(ast),
-            ...handler
-          }
-        }
+        return mergeRefinements(
+          go(ast.from, $defs, handleIdentifier, path, options),
+          handler,
+          getJsonSchemaAnnotations(ast)
+        )
       } else if (!isOverrideAnnotation(handler)) {
-        return go(t, $defs, true, path)
+        return go(t, $defs, handleIdentifier, path, options)
       }
     }
     return handler
   }
   const surrogate = AST.getSurrogateAnnotation(ast)
   if (Option.isSome(surrogate)) {
-    return go(surrogate.value, $defs, handleIdentifier, path)
-  }
-  if (handleIdentifier && !AST.isTransformation(ast) && !AST.isRefinement(ast)) {
-    const identifier = AST.getJSONIdentifier(ast)
-    if (Option.isSome(identifier)) {
-      const id = identifier.value
-      const out = { $ref: get$ref(id) }
-      if (!Record.has($defs, id)) {
-        $defs[id] = out
-        $defs[id] = go(ast, $defs, false, path)
-      }
-      return out
-    }
+    return go(surrogate.value, $defs, handleIdentifier, path, options)
   }
   switch (ast._tag) {
     case "Declaration":
@@ -391,9 +487,9 @@ const go = (
     case "Literal": {
       const literal = ast.literal
       if (literal === null) {
-        return merge({ enum: [null] }, getJsonSchemaAnnotations(ast))
+        return { enum: [null], ...getJsonSchemaAnnotations(ast) }
       } else if (Predicate.isString(literal) || Predicate.isNumber(literal) || Predicate.isBoolean(literal)) {
-        return merge({ enum: [literal] }, getJsonSchemaAnnotations(ast))
+        return { enum: [literal], ...getJsonSchemaAnnotations(ast) }
       }
       throw new Error(errors_.getJSONSchemaMissingAnnotationErrorMessage(path, ast))
     }
@@ -402,15 +498,15 @@ const go = (
     case "UndefinedKeyword":
       throw new Error(errors_.getJSONSchemaMissingAnnotationErrorMessage(path, ast))
     case "VoidKeyword":
-      return merge(voidJsonSchema, getJsonSchemaAnnotations(ast))
+      return { ...constVoid, ...getJsonSchemaAnnotations(ast) }
     case "NeverKeyword":
-      throw new Error(errors_.getJSONSchemaMissingAnnotationErrorMessage(path, ast))
+      return { ...constNever, ...getJsonSchemaAnnotations(ast) }
     case "UnknownKeyword":
-      return merge(unknownJsonSchema, getJsonSchemaAnnotations(ast))
+      return { ...constUnknown, ...getJsonSchemaAnnotations(ast) }
     case "AnyKeyword":
-      return merge(anyJsonSchema, getJsonSchemaAnnotations(ast))
+      return { ...constAny, ...getJsonSchemaAnnotations(ast) }
     case "ObjectKeyword":
-      return merge(objectJsonSchema, getJsonSchemaAnnotations(ast))
+      return { ...constAnyObject, ...getJsonSchemaAnnotations(ast) }
     case "StringKeyword":
       return { type: "string", ...getASTJsonSchemaAnnotations(ast) }
     case "NumberKeyword":
@@ -422,18 +518,14 @@ const go = (
     case "SymbolKeyword":
       throw new Error(errors_.getJSONSchemaMissingAnnotationErrorMessage(path, ast))
     case "TupleType": {
-      const elements = ast.elements.map((e, i) =>
-        merge(
-          go(e.type, $defs, true, path.concat(i)),
-          getJsonSchemaAnnotations(e)
-        )
-      )
-      const rest = ast.rest.map((annotatedAST) =>
-        merge(
-          go(annotatedAST.type, $defs, true, path),
-          getJsonSchemaAnnotations(annotatedAST)
-        )
-      )
+      const elements = ast.elements.map((e, i) => ({
+        ...go(e.type, $defs, true, path.concat(i), options),
+        ...getJsonSchemaAnnotations(e)
+      }))
+      const rest = ast.rest.map((annotatedAST) => ({
+        ...go(annotatedAST.type, $defs, true, path, options),
+        ...getJsonSchemaAnnotations(annotatedAST)
+      }))
       const output: JsonSchema7Array = { type: "array" }
       // ---------------------------------------------
       // handle elements
@@ -470,11 +562,11 @@ const go = (
         }
       }
 
-      return merge(output, getJsonSchemaAnnotations(ast))
+      return { ...output, ...getJsonSchemaAnnotations(ast) }
     }
     case "TypeLiteral": {
       if (ast.propertySignatures.length === 0 && ast.indexSignatures.length === 0) {
-        return merge(empty(), getJsonSchemaAnnotations(ast))
+        return { ...constEmpty, ...getJsonSchemaAnnotations(ast) }
       }
       let patternProperties: JsonSchema7 | undefined = undefined
       let propertyNames: JsonSchema7 | undefined = undefined
@@ -482,11 +574,11 @@ const go = (
         const parameter = is.parameter
         switch (parameter._tag) {
           case "StringKeyword": {
-            patternProperties = go(is.type, $defs, true, path)
+            patternProperties = go(is.type, $defs, true, path, options)
             break
           }
           case "TemplateLiteral": {
-            patternProperties = go(is.type, $defs, true, path)
+            patternProperties = go(is.type, $defs, true, path, options)
             propertyNames = {
               type: "string",
               pattern: AST.getTemplateLiteralRegExp(parameter).source
@@ -494,8 +586,8 @@ const go = (
             break
           }
           case "Refinement": {
-            patternProperties = go(is.type, $defs, true, path)
-            propertyNames = go(parameter, $defs, true, path)
+            patternProperties = go(is.type, $defs, true, path, options)
+            propertyNames = go(parameter, $defs, true, path, options)
             break
           }
           case "SymbolKeyword":
@@ -516,10 +608,10 @@ const go = (
         const name = ps.name
         if (Predicate.isString(name)) {
           const pruned = pruneUndefinedFromPropertySignature(ps.type)
-          output.properties[name] = merge(
-            go(pruned ? pruned : ps.type, $defs, true, path.concat(ps.name)),
-            getJsonSchemaAnnotations(ps)
-          )
+          output.properties[name] = {
+            ...go(pruned ?? ps.type, $defs, true, path.concat(ps.name), options),
+            ...getJsonSchemaAnnotations(ps)
+          }
           // ---------------------------------------------
           // handle optional property signatures
           // ---------------------------------------------
@@ -541,69 +633,76 @@ const go = (
         output.propertyNames = propertyNames
       }
 
-      return merge(output, getJsonSchemaAnnotations(ast))
+      return { ...output, ...getJsonSchemaAnnotations(ast) }
     }
     case "Union": {
-      const enums: Array<AST.LiteralValue> = []
       const anyOf: Array<JsonSchema7> = []
       for (const type of ast.types) {
-        const schema = go(type, $defs, true, path)
+        const schema = go(type, $defs, true, path, options)
         if ("enum" in schema) {
           if (Object.keys(schema).length > 1) {
             anyOf.push(schema)
           } else {
-            for (const e of schema.enum) {
-              enums.push(e)
+            const last = anyOf[anyOf.length - 1]
+            if (last !== undefined && isEnumOnly(last)) {
+              for (const e of schema.enum) {
+                last.enum.push(e)
+              }
+            } else {
+              anyOf.push(schema)
             }
           }
         } else {
           anyOf.push(schema)
         }
       }
-      if (anyOf.length === 0) {
-        return merge({ enum: enums }, getJsonSchemaAnnotations(ast))
+      if (anyOf.length === 1 && isEnumOnly(anyOf[0])) {
+        return { enum: anyOf[0].enum, ...getJsonSchemaAnnotations(ast) }
       } else {
-        if (enums.length >= 1) {
-          anyOf.push({ enum: enums })
-        }
-        return merge({ anyOf }, getJsonSchemaAnnotations(ast))
+        return { anyOf, ...getJsonSchemaAnnotations(ast) }
       }
     }
     case "Enums": {
-      return merge({
+      return {
         $comment: "/schemas/enums",
-        anyOf: ast.enums.map((e) => ({ title: e[0], enum: [e[1]] }))
-      }, getJsonSchemaAnnotations(ast))
+        anyOf: ast.enums.map((e) => ({ title: e[0], enum: [e[1]] })),
+        ...getJsonSchemaAnnotations(ast)
+      }
     }
     case "Refinement": {
-      if (AST.encodedBoundAST(ast) === ast) {
+      // The jsonSchema annotation is required only if the refinement does not have a transformation
+      if (AST.getTransformationFrom(ast) === undefined) {
         throw new Error(errors_.getJSONSchemaMissingAnnotationErrorMessage(path, ast))
       }
-      return go(ast.from, $defs, true, path)
+      return go(ast.from, $defs, handleIdentifier, path, options)
     }
     case "TemplateLiteral": {
       const regex = AST.getTemplateLiteralRegExp(ast)
-      return merge({
+      return {
         type: "string",
         title: String(ast),
         description: "a template literal",
-        pattern: regex.source
-      }, getJsonSchemaAnnotations(ast))
+        pattern: regex.source,
+        ...getJsonSchemaAnnotations(ast)
+      }
     }
     case "Suspend": {
       const identifier = Option.orElse(AST.getJSONIdentifier(ast), () => AST.getJSONIdentifier(ast.f()))
       if (Option.isNone(identifier)) {
         throw new Error(errors_.getJSONSchemaMissingIdentifierAnnotationErrorMessage(path, ast))
       }
-      return go(ast.f(), $defs, true, path)
+      return go(ast.f(), $defs, handleIdentifier, path, options)
     }
     case "Transformation": {
-      // Properly handle S.parseJson transformations by focusing on
-      // the 'to' side of the AST. This approach prevents the generation of useless schemas
-      // derived from the 'from' side (type: string), ensuring the output matches the intended
-      // complex schema type.
       if (isParseJsonTransformation(ast.from)) {
-        return go(ast.to, $defs, true, path)
+        const out: JsonSchema7String & { contentSchema?: JsonSchema7 } = {
+          "type": "string",
+          "contentMediaType": "application/json"
+        }
+        if (options.target !== "jsonSchema7") {
+          out["contentSchema"] = go(ast.to, $defs, handleIdentifier, path, options)
+        }
+        return out
       }
       let next = ast.from
       if (AST.isTypeLiteralTransformation(ast.transformation)) {
@@ -622,7 +721,7 @@ const go = (
           next = AST.annotations(next, { [AST.DescriptionAnnotationId]: description.value })
         }
       }
-      return go(next, $defs, true, path)
+      return go(next, $defs, handleIdentifier, path, options)
     }
   }
 }

package/src/Schema.ts

@@ -2632,7 +2632,9 @@ export interface TypeLiteral<
     annotations: Annotations.Schema<Simplify<TypeLiteral.Type<Fields, Records>>>
   ): TypeLiteral<Fields, Records>
   make(
-    props: Simplify<TypeLiteral.Constructor<Fields, Records>>,
+    props: RequiredKeys<TypeLiteral.Constructor<Fields, Records>> extends never
+      ? void | Simplify<TypeLiteral.Constructor<Fields, Records>>
+      : Simplify<TypeLiteral.Constructor<Fields, Records>>,
     options?: MakeOptions
   ): Simplify<TypeLiteral.Type<Fields, Records>>
 }
@@ -4669,6 +4671,7 @@ export const lowercased =
       filter((a) => a === a.toLowerCase(), {
         schemaId: LowercasedSchemaId,
         description: "a lowercase string",
+        jsonSchema: { pattern: "^[^A-Z]*$" },
         ...annotations
       })
     )
@@ -4699,6 +4702,7 @@ export const capitalized =
       filter((a) => a[0]?.toUpperCase() === a[0], {
         schemaId: CapitalizedSchemaId,
         description: "a capitalized string",
+        jsonSchema: { pattern: "^[^a-z]?.*$" },
         ...annotations
       })
     )
@@ -4729,6 +4733,7 @@ export const uncapitalized =
       filter((a) => a[0]?.toLowerCase() === a[0], {
         schemaId: UncapitalizedSchemaId,
         description: "a uncapitalized string",
+        jsonSchema: { pattern: "^[^A-Z]?.*$" },
         ...annotations
       })
     )
@@ -4759,6 +4764,7 @@ export const uppercased =
       filter((a) => a === a.toUpperCase(), {
         schemaId: UppercasedSchemaId,
         description: "an uppercase string",
+        jsonSchema: { pattern: "^[^a-z]*$" },
         ...annotations
       })
     )
@@ -4947,7 +4953,7 @@ export type ParseJsonOptions = {
 const JsonString = String$.annotations({
   [AST.IdentifierAnnotationId]: "JsonString",
   [AST.TitleAnnotationId]: "JsonString",
-  [AST.DescriptionAnnotationId]: "a JSON string"
+  [AST.DescriptionAnnotationId]: "a string that will be parsed as JSON"
 })
 
 const getParseJsonTransformation = (options?: ParseJsonOptions) =>
@@ -6401,7 +6407,7 @@ export const minItems = <A>(
       (a) => a.length >= minItems,
       {
         schemaId: MinItemsSchemaId,
-        description: `an array of at least ${minItems} items`,
+        description: `an array of at least ${minItems} item(s)`,
         jsonSchema: { minItems },
         [AST.StableFilterAnnotationId]: true,
         ...annotations
@@ -6434,7 +6440,7 @@ export const maxItems = <A>(
   self.pipe(
     filter((a) => a.length <= n, {
       schemaId: MaxItemsSchemaId,
-      description: `an array of at most ${n} items`,
+      description: `an array of at most ${n} item(s)`,
       jsonSchema: { maxItems: n },
       [AST.StableFilterAnnotationId]: true,
       ...annotations
@@ -8738,10 +8744,16 @@ const makeClass = ({ Base, annotations, disableToString, fields, identifier, kin
   disableToString?: boolean | undefined
 }): any => {
   const classSymbol = Symbol.for(`effect/Schema/${kind}/${identifier}`)
+
+  const ts = typeSchema(schema)
+  const declarationSurrogate = ts.annotations({ identifier, ...annotations })
+  const typeSide = ts.annotations({ [AST.AutoTitleAnnotationId]: `${identifier} (Type side)` })
+  const transformationSurrogate = schema.annotations({ ...annotations })
   const validateSchema = schema.annotations({ [AST.AutoTitleAnnotationId]: `${identifier} (Constructor)` })
-  const encodedSide: Schema.Any = schema.annotations({ [AST.AutoTitleAnnotationId]: `${identifier} (Encoded side)` })
-  const typeSide = typeSchema(schema).annotations({ [AST.AutoTitleAnnotationId]: `${identifier} (Type side)` })
+  const encodedSide = schema.annotations({ [AST.AutoTitleAnnotationId]: `${identifier} (Encoded side)` })
+
   const fallbackInstanceOf = (u: unknown) => Predicate.hasProperty(u, classSymbol) && ParseResult.is(typeSide)(u)
+
   const klass = class extends Base {
     constructor(
       props: { [x: string | symbol]: unknown } = {},
@@ -8768,6 +8780,7 @@ const makeClass = ({ Base, annotations, disableToString, fields, identifier, kin
       if (astCache.has(this)) {
         return astCache.get(this)!
       }
+
       const declaration: Schema.Any = declare(
         [typeSide],
         {
@@ -8785,21 +8798,23 @@ const makeClass = ({ Base, annotations, disableToString, fields, identifier, kin
         },
         {
           identifier,
-          title: identifier,
-          description: `an instance of ${identifier}`,
           pretty: (pretty) => (self: any) => `${identifier}(${pretty(self)})`,
           // @ts-expect-error
           arbitrary: (arb) => (fc) => arb(fc).map((props) => new this(props)),
           equivalence: identity,
-          [AST.SurrogateAnnotationId]: typeSide.ast,
+          [AST.SurrogateAnnotationId]: declarationSurrogate.ast,
           ...annotations
         }
       )
+
       const transformation = transform(
         encodedSide,
         declaration,
         { strict: true, decode: (input) => new this(input, true), encode: identity }
-      ).annotations({ [AST.SurrogateAnnotationId]: schema.ast })
+      ).annotations({
+        [AST.JSONIdentifierAnnotationId]: identifier,
+        [AST.SurrogateAnnotationId]: transformationSurrogate.ast
+      })
       astCache.set(this, transformation.ast)
       return transformation.ast
     }