effect 4.0.0-beta.103 → 4.0.0-beta.105

package/dist/Schema.js

@@ -81,7 +81,7 @@ const TypeId = InternalSchema.TypeId;
  * **Example** (Schema for a parametric `Box<A>` type)
  *
  * ```ts import.meta.vitest
- * import { Effect, Schema, SchemaIssue as Issue, SchemaParser } from "effect"
+ * import { Effect, Schema, SchemaIssue, SchemaParser } from "effect"
  *
  * interface Box<A> {
  *   readonly value: A
@@ -96,7 +96,7 @@ const TypeId = InternalSchema.TypeId;
  *     ([itemCodec]) =>
  *       (u, ast, options) => {
  *         if (!isBox(u)) {
- *           return Effect.fail(new SchemaIssue.InvalidType(ast))
+ *           return Effect.fail(new SchemaIssue.InvalidType(ast, u, options))
  *         }
  *         return Effect.map(
  *           SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options),
@@ -150,7 +150,7 @@ export function declareConstructor() {
  * @since 3.10.0
  */
 export function declare(is, annotations) {
-  return declareConstructor()([], () => (input, ast) => is(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast)), annotations);
+  return declareConstructor()([], () => (input, ast, options) => is(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast, input, options)), annotations);
 }
 /**
  * Returns a schema widened to the fully-parameterized {@link Bottom} interface,
@@ -338,10 +338,12 @@ isSchemaError,
  *
  * The `issue` field contains a structured {@link SchemaIssue.Issue} tree describing
  * every validation failure, including the path to the problematic value and
- * the expected type or constraint. Built-in issues have no `actual` field,
- * and built-in messages do not include the rejected value. Other Issue fields
- * and custom annotations or messages are not sanitized. `message` renders the
- * issue tree as a human-readable string.
+ * the expected type or constraint. Parsing with `reportInput: true` adds an
+ * enumerable `input` field to value-bearing issues created by the parser.
+ * Built-in messages may include reported input. Other issue fields and
+ * custom annotations or messages are not sanitized.
+ * `message` renders the issue tree as a human-readable string and can disclose
+ * retained input.
  *
  * Use {@link isSchemaError} to narrow an unknown value to `SchemaError`.
  *
@@ -584,6 +586,9 @@ export const is = SchemaParser.is;
  *
  * The input is narrowed if the assertion succeeds. If schema validation fails,
  * the assertion throws an `Error` whose cause is `SchemaIssue.Issue`.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -641,9 +646,12 @@ export const asserts = SchemaParser.asserts;
 export function decodeUnknownEffect(schema, options) {
   const parser = SchemaParser.decodeUnknownEffect(schema, options);
   return (input, options) => {
-    return InternalSchema.fromIssueEffect(parser(input, options));
+    return fromIssueEffect(parser(input, options));
   };
 }
+function fromIssueEffect(self) {
+  return Effect.catchCause(self, cause => Effect.failCauseSync(() => Cause_.map(cause, issue => new SchemaError(issue))));
+}
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Effect` that succeeds with the decoded value or fails with a
@@ -1050,7 +1058,7 @@ export const decodeSync = decodeUnknownSync;
 export function encodeUnknownEffect(schema, options) {
   const parser = SchemaParser.encodeUnknownEffect(schema, options);
   return (input, options) => {
-    return InternalSchema.fromIssueEffect(parser(input, options));
+    return fromIssueEffect(parser(input, options));
   };
 }
 /**
@@ -2706,7 +2714,7 @@ export function encode(transformation) {
  * **Details**
  *
  * Constructor defaults are applied only during `make*`, not during decoding or
- * encoding.
+ * encoding. Failures are represented directly as `SchemaIssue.Issue` values.
  *
  * **Example** (Defining an optional field with a static default)
  *
@@ -2730,7 +2738,7 @@ export function withConstructorDefault(
 // `S["~type.make.in"]` instead of `S["Type"]` is intentional here because
 // it makes easier to define the default value if there are nested defaults
 defaultValue) {
-  return schema => make(SchemaAST.withConstructorDefault(schema.ast, toIssueEffect(defaultValue)), {
+  return schema => make(SchemaAST.withConstructorDefault(schema.ast, defaultValue), {
     schema
   });
 }
@@ -5903,7 +5911,7 @@ export function isPropertyNames(keySchema, annotations) {
       }
     }
     if (Arr.isArrayNonEmpty(issues)) {
-      return new SchemaIssue.Composite(ast, issues);
+      return new SchemaIssue.Composite(ast, issues, input, options);
     }
     return true;
   }, {
@@ -6037,10 +6045,10 @@ export function Option(value) {
       }
       return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(value)(input.value, options), {
         onSuccess: Option_.some,
-        onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], issue)])
+        onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "value", issue, input, options)
       });
     }
-    return Effect.fail(new SchemaIssue.InvalidType(ast));
+    return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
   }, {
     representation: {
       id: "effect/schema/Option",
@@ -6208,18 +6216,18 @@ export function OptionFromOptionalNullOr(schema, options) {
 export function Result(success, failure) {
   const schema = declareConstructor()([success, failure], ([success, failure]) => (input, ast, options) => {
     if (!Result_.isResult(input)) {
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     }
     switch (input._tag) {
       case "Success":
         return Effect.mapBothEager(SchemaParser.decodeEffect(success)(input.success, options), {
           onSuccess: Result_.succeed,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["success"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "success", issue, input, options)
         });
       case "Failure":
         return Effect.mapBothEager(SchemaParser.decodeEffect(failure)(input.failure, options), {
           onSuccess: Result_.fail,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["failure"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "failure", issue, input, options)
         });
     }
   }, {
@@ -6340,11 +6348,11 @@ export function Redacted(value, options) {
         onSuccess: () => input,
         onFailure: (/** ignore the issue because of security reasons */
         ) => {
-          return new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], new SchemaIssue.InvalidValue())]);
+          return new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], new SchemaIssue.InvalidValue(undefined, input, poptions))], input, poptions);
         }
       }));
     }
-    return Effect.fail(new SchemaIssue.InvalidType(ast));
+    return Effect.fail(new SchemaIssue.InvalidType(ast, input, poptions));
   }, {
     representation: {
       id: "effect/schema/Redacted",
@@ -6442,18 +6450,18 @@ export function RedactedFromValue(value, options) {
 export function CauseReason(error, defect) {
   const schema = declareConstructor()([error, defect], ([error, defect]) => (input, ast, options) => {
     if (!Cause_.isReason(input)) {
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     }
     switch (input._tag) {
       case "Fail":
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(error)(input.error, options), {
           onSuccess: Cause_.makeFailReason,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["error"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "error", issue, input, options)
         });
       case "Die":
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(defect)(input.defect, options), {
           onSuccess: Cause_.makeDieReason,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["defect"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "defect", issue, input, options)
         });
       case "Interrupt":
         return Effect.succeed(input);
@@ -6581,11 +6589,11 @@ export function Cause(error, defect) {
     const failures = ArraySchema(CauseReason(error, defect));
     return (input, ast, options) => {
       if (!Cause_.isCause(input)) {
-        return Effect.fail(new SchemaIssue.InvalidType(ast));
+        return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
       }
       return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(failures)(input.reasons, options), {
         onSuccess: Cause_.fromReasons,
-        onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["failures"], issue)])
+        onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "failures", issue, input, options)
       });
     };
   }, {
@@ -6695,7 +6703,7 @@ const errorSchemaCache = [];
  * @category schemas
  * @since 4.0.0
  */
-export function Error(options) {
+export function ErrorInstance(options) {
   const key = getErrorOptionsKey(options);
   const cached = errorSchemaCache[key];
   if (cached !== undefined) {
@@ -6708,7 +6716,7 @@ export function Error(options) {
       payload: normalizedOptions ?? null
     },
     toCode: () => ({
-      runtime: normalizedOptions !== undefined ? `Schema.Error(${format(normalizedOptions)})` : `Schema.Error()`,
+      runtime: normalizedOptions !== undefined ? `Schema.ErrorInstance(${format(normalizedOptions)})` : `Schema.ErrorInstance()`,
       Type: `globalThis.Error`
     }),
     expected: "Error",
@@ -6719,22 +6727,22 @@ export function Error(options) {
   return schema;
 }
 /**
- * Reviver for persisted {@link Error} declarations.
+ * Reviver for persisted {@link ErrorInstance} declarations.
  *
  * **When to use**
  *
- * Use when reconstructing documents that may contain schemas created by {@link Error}.
+ * Use when reconstructing documents that may contain schemas created by {@link ErrorInstance}.
  *
- * @see {@link Error} for creating the corresponding schema
+ * @see {@link ErrorInstance} for creating the corresponding schema
  *
  * @category schemas
  * @since 4.0.0
  */
-export const ErrorReviver = /*#__PURE__*/InternalSchema.makeDeclarationReviver("effect/schema/Error", ErrorRepresentationPayload, ({
+export const ErrorInstanceReviver = /*#__PURE__*/InternalSchema.makeDeclarationReviver("effect/schema/Error", ErrorRepresentationPayload, ({
   annotations,
   payload
 }) => {
-  const schema = Error(payload ?? undefined);
+  const schema = ErrorInstance(payload ?? undefined);
   return annotations === undefined ? schema : schema.annotate(annotations);
 });
 const defectSchemaCache = [];
@@ -6775,7 +6783,7 @@ const defectSchemaCache = [];
  * - Values that cannot be represented as JSON fall back to Effect's formatted
  *   string representation.
  *
- * @see {@link Error} for a schema that only accepts JavaScript `Error` values.
+ * @see {@link ErrorInstance} for a schema that only accepts JavaScript `Error` values.
  * @category schemas
  * @since 4.0.0
  */
@@ -6806,18 +6814,18 @@ export function Exit(value, error, defect) {
     const cause = Cause(error, defect);
     return (input, ast, options) => {
       if (!Exit_.isExit(input)) {
-        return Effect.fail(new SchemaIssue.InvalidType(ast));
+        return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
       }
       switch (input._tag) {
         case "Success":
           return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(value)(input.value, options), {
             onSuccess: Exit_.succeed,
-            onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], issue)])
+            onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "value", issue, input, options)
           });
         case "Failure":
           return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(cause)(input.cause, options), {
             onSuccess: Exit_.failCause,
-            onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["cause"], issue)])
+            onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "cause", issue, input, options)
           });
       }
     };
@@ -6961,10 +6969,10 @@ export function ReadonlyMap(key, value) {
       if (input instanceof globalThis.Map) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(array)([...input], options), {
           onSuccess: array => new globalThis.Map(array),
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["entries"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "entries", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7030,10 +7038,10 @@ export function HashMap(key, value) {
       if (HashMap_.isHashMap(input)) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(entries)(HashMap_.toEntries(input), options), {
           onSuccess: HashMap_.fromIterable,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["entries"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "entries", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7100,10 +7108,10 @@ export function ReadonlySet(value) {
       if (input instanceof globalThis.Set) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(array)([...input], options), {
           onSuccess: array => new globalThis.Set(array),
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7168,10 +7176,10 @@ export function HashSet(value) {
       if (HashSet_.isHashSet(input)) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
           onSuccess: HashSet_.fromIterable,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7236,10 +7244,10 @@ export function Chunk(value) {
       if (Chunk_.isChunk(input)) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
           onSuccess: Chunk_.fromIterable,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7315,11 +7323,11 @@ export const RegExp = /*#__PURE__*/instanceOf(globalThis.RegExp, {
     source: String,
     flags: String
   }), SchemaTransformation.transformOrFail({
-    decode: e => Effect.try({
+    decode: (e, options) => Effect.try({
       try: () => new globalThis.RegExp(e.source, e.flags),
       catch: () => new SchemaIssue.InvalidValue({
-        message: "Expected valid RegExp source and flags"
-      })
+        expected: "valid RegExp source and flags"
+      }, e, options)
     }),
     encode: regExp => Effect.succeed({
       source: regExp.source,
@@ -7894,10 +7902,10 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
     name: String,
     lastModified: Int
   }), SchemaTransformation.transformOrFail({
-    decode: e => Result_.match(Encoding.decodeBase64(e.data), {
+    decode: (e, options) => Result_.match(Encoding.decodeBase64(e.data), {
       onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
-        message: "Expected a valid Base64 string"
-      })),
+        expected: "a valid Base64 string"
+      }, e.data, options)),
       onSuccess: bytes => {
         const buffer = new globalThis.Uint8Array(bytes);
         return Effect.succeed(new globalThis.File([buffer], e.name, {
@@ -7906,7 +7914,7 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
         }));
       }
     }),
-    encode: file => Effect.tryPromise({
+    encode: (file, options) => Effect.tryPromise({
       try: async () => {
         const bytes = new globalThis.Uint8Array(await file.arrayBuffer());
         return {
@@ -7917,8 +7925,8 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
         };
       },
       catch: () => new SchemaIssue.InvalidValue({
-        message: "Expected File to be readable"
-      })
+        expected: "a readable File"
+      }, file, options)
     })
   }))
 });
@@ -8985,12 +8993,17 @@ function getClassSchemaFactory(from, identifier, annotations) {
     if (memo !== undefined) {
       return memo;
     }
+    const ClassTypeId = getClassTypeId(identifier);
+    const isClassValue = input => input instanceof self || Predicate.hasProperty(input, ClassTypeId);
     const transformation = getClassTransformation(self);
-    const to = make(new SchemaAST.Declaration([from.ast], () => (input, ast) => {
-      return input instanceof self || Predicate.hasProperty(input, getClassTypeId(identifier)) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast));
+    const to = make(new SchemaAST.Declaration([from.ast], () => (input, ast, options) => {
+      return isClassValue(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     }, {
       identifier,
-      [SchemaAST.ClassTypeId]: ([from]) => new SchemaAST.Link(from, transformation),
+      [InternalAnnotations.CONSTRUCTOR_ANNOTATION_KEY]: ([from]) => ({
+        isConstructed: isClassValue,
+        link: new SchemaAST.Link(from, transformation)
+      }),
       toCodec: ([from]) => new SchemaAST.Link(from.ast, transformation),
       toArbitrary: ([from]) => () => ({
         arbitrary: from.arbitrary.map(args => new self(args)),
@@ -9008,8 +9021,8 @@ function isStruct(schema) {
 }
 /**
  * Creates a schema-backed class whose constructor validates input against a
- * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
- * input.
+ * {@link Struct} schema. Construction throws an `Error` with a
+ * `SchemaIssue.Issue` in its `cause` on invalid input.
  *
  * **When to use**
  *
@@ -9069,8 +9082,8 @@ function isStruct(schema) {
  * ```
  *
  * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
- * @see {@link ErrorClass} for defining schema-backed error classes
- * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+ * @see {@link Error} for defining schema-backed error classes
+ * @see {@link TaggedError} for defining tagged schema-backed error classes
  *
  * @category constructors
  * @since 3.10.0
@@ -9137,7 +9150,7 @@ export const TaggedClass = identifier => {
  * ```ts import.meta.vitest
  * import { Effect, Schema } from "effect"
  *
- * class NotFound extends Schema.ErrorClass<NotFound>("NotFound")({
+ * class NotFound extends Schema.Error<NotFound>("NotFound")({
  *   id: Schema.Number
  * }) {}
  *
@@ -9151,7 +9164,7 @@ export const TaggedClass = identifier => {
  * @category constructors
  * @since 4.0.0
  */
-export const ErrorClass = identifier => (schema, annotations) => {
+export const Error = identifier => (schema, annotations) => {
   const struct = isStruct(schema) ? schema : Struct(schema);
   const self = makeClass(core.Error, identifier, struct, annotations, identifier => ({
     name: identifier
@@ -9172,7 +9185,7 @@ export const ErrorClass = identifier => (schema, annotations) => {
  * ```ts import.meta.vitest
  * import { Effect, Schema } from "effect"
  *
- * class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+ * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
  *   id: Schema.Number
  * }) {}
  *
@@ -9187,7 +9200,7 @@ export const ErrorClass = identifier => (schema, annotations) => {
  * @category constructors
  * @since 3.10.0
  */
-export const TaggedErrorClass = identifier => {
+export const TaggedError = identifier => {
   return (tagValue, schema, annotations) => {
     const struct = isStruct(schema) ? schema.mapFields(fields => ({
       _tag: tag(tagValue),
@@ -9195,7 +9208,7 @@ export const TaggedErrorClass = identifier => {
     }), {
       unsafePreserveChecks: true
     }) : TaggedStruct(tagValue, schema);
-    return ErrorClass(identifier ?? tagValue)(struct, annotations);
+    return Error(identifier ?? tagValue)(struct, annotations);
   };
 };
 /**
@@ -9507,7 +9520,7 @@ const toCodecJsonASTBase = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(
 /** @internal */
 export const toCodecJsonAST = /*#__PURE__*/memoize(toCodecJsonASTBase);
 function withoutConstructorDefault(context) {
-  return context.defaultValue === undefined ? context : new SchemaAST.Context(context.isOptional, context.isMutable, undefined, context.annotations);
+  return context.constructorDefault === undefined ? context : new SchemaAST.Context(context.isOptional, context.isMutable, undefined, context.annotations);
 }
 function validateCanonicalObjectPropertyNames(ast) {
   if (ast.propertySignatures.some(ps => typeof ps.name !== "string")) {
@@ -10068,6 +10081,18 @@ export const isBetweenBigIntReviver = /*#__PURE__*/InternalSchema.makeFilterRevi
  * Derives an `Iso` optic from a schema that isomorphically converts between
  * the schema's `Type` and its `Iso` (intermediate / serialized form).
  *
+ * **Details**
+ *
+ * Reading through the `Iso` encodes the schema value, while replacing through
+ * it decodes the new focus.
+ *
+ * **Gotchas**
+ *
+ * Either direction can throw an `Error` with the generic message
+ * `"Schema validation failed"` and a `SchemaIssue.Issue` in its `cause`. Format
+ * the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -10127,6 +10152,19 @@ export function overrideToCodecIso(to, transformation) {
  * {@link toCodecJson}), computes RFC 6902 JSON Patch operations between old
  * and new values, and can apply patches back to the typed value.
  *
+ * **Details**
+ *
+ * `diff` encodes both values before computing the patch. `patch` encodes the old
+ * value, applies the patch to its JSON representation, and decodes the result.
+ *
+ * **Gotchas**
+ *
+ * Schema encoding or decoding failures throw an `Error` with the generic message
+ * `"Schema validation failed"` and a `SchemaIssue.Issue` in its `cause`. Format
+ * the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed. Errors produced by {@link JsonPatch.apply}
+ * for invalid patch operations are separate from schema validation failures.
+ *
  * @category converting
  * @since 4.0.0
  */