LeafUnion of all terminal (leaf) issue types that have no inner Issue children.
When to use
Use when constraining formatter hooks to only handle terminal nodes or when
pattern matching on the _tag of an issue and only leaf nodes matter.
Details
Members: InvalidType, InvalidValue, MissingKey, UnexpectedKey, Forbidden, OneOf.
export type type Leaf =
| InvalidType
| InvalidValue
| MissingKey
| UnexpectedKey
| Forbidden
| OneOf
Union of all terminal (leaf) issue types that have no inner Issue children.
When to use
Use when constraining formatter hooks to only handle terminal nodes or when
pattern matching on the _tag of an issue and only leaf nodes matter.
Details
Members:
InvalidType
,
InvalidValue
,
MissingKey
,
UnexpectedKey
,
Forbidden
,
OneOf
.
Leaf =
| class InvalidTypeclass InvalidType {
_tag: 'InvalidType';
ast: SchemaAST.AST;
actual: Option.Option<unknown>;
toString: (this: Issue) => string;
}
Represents a schema issue produced when the runtime type of the input does not match the type
expected by the schema (e.g. got null when string was expected).
When to use
Use when you need to detect basic type mismatches, such as a wrong primitive
or null where an object was expected.
Details
ast is the schema node that expected a different type.actual is Option.some(value) when the input was present, or
Option.none() when no value was provided.- The default formatter renders this as
"Expected <type>, got <actual>".
Example (Formatting output)
import { Schema } from "effect"
try {
Schema.decodeUnknownSync(Schema.String)(42)
} catch (e) {
if (Schema.isSchemaError(e)) {
console.log(String(e.issue))
// "Expected string, got 42"
}
}
InvalidType
| class InvalidValueclass InvalidValue {
_tag: 'InvalidValue';
actual: Option.Option<unknown>;
annotations: Schema.Annotations.Issue | undefined;
toString: (this: Issue) => string;
}
Represents a schema issue produced when the input has the correct type but its value violates a
constraint (e.g. a string that is too short, a number out of range).
When to use
Use when you need to detect constraint violations from Schema.filter,
Schema.minLength, Schema.greaterThan, or similar checks.
Details
actual is Option.some(value) when the failing value is known, or
Option.none() when absent.annotations optionally carries a message string for formatting.- The default formatter renders this as
"Invalid data <actual>" unless a
custom message annotation is provided.
Example (Returning InvalidValue from a custom filter)
import { Option, SchemaIssue } from "effect"
const issue = new SchemaIssue.InvalidValue(
Option.some(""),
{ message: "must not be empty" }
)
console.log(String(issue))
// "must not be empty"
InvalidValue
| class MissingKeyclass MissingKey {
_tag: 'MissingKey';
annotations: Schema.Annotations.Key<unknown> | undefined;
toString: (this: Issue) => string;
}
Represents a schema issue produced when a required key or tuple index is missing from the input.
When to use
Use when you need to detect absent fields in struct/tuple validation.
Details
- Has no
actual value —
getActual
returns Option.none().
annotations may contain a custom messageMissingKey for formatting.
MissingKey
| class UnexpectedKeyclass UnexpectedKey {
_tag: 'UnexpectedKey';
ast: SchemaAST.AST;
actual: unknown;
toString: (this: Issue) => string;
}
Represents a schema issue produced when an input object or tuple contains a key/index not
declared by the schema.
When to use
Use when you need to detect excess properties during strict struct/tuple
validation.
Details
actual is the raw value at the unexpected key (plain unknown).ast is the schema that was being validated against.annotations on ast may contain a custom messageUnexpectedKey.
UnexpectedKey
| class Forbiddenclass Forbidden {
_tag: 'Forbidden';
actual: Option.Option<unknown>;
annotations: Schema.Annotations.Issue | undefined;
toString: (this: Issue) => string;
}
Represents a schema issue produced when a forbidden operation is encountered during parsing,
such as an asynchronous Effect running inside Schema.decodeUnknownSync.
When to use
Use when you need to detect that a schema requires async execution but was run
synchronously.
Details
actual is Option.some(value) when the input is known, or
Option.none() when absent.annotations optionally carries a message string.- The default formatter renders this as
"Forbidden operation".
Example (Creating a Forbidden issue)
import { Option, SchemaIssue } from "effect"
const issue = new SchemaIssue.Forbidden(
Option.none(),
{ message: "async operation not allowed in sync context" }
)
console.log(String(issue))
// "async operation not allowed in sync context"
Forbidden
| class OneOfclass OneOf {
_tag: 'OneOf';
ast: SchemaAST.Union;
actual: unknown;
successes: ReadonlyArray<SchemaAST.AST>;
toString: (this: Issue) => string;
}
Represents a schema issue produced when a value matches multiple members of a union that is
configured to allow exactly one match (oneOf mode).
When to use
Use when you need to detect ambiguous union matches when oneOf validation is
enabled.
Details
ast is the Union AST node.actual is the raw input value (plain unknown).successes lists the AST nodes of each member that accepted the input.- The default formatter renders this as
"Expected exactly one member to match the input <actual>".
OneOf