Validation Rules
Constraints turn “a string” into “an email between 2 and 50 characters.” Chain them onto any schema — each comes with a sensible default error message, and you can supply your own (see Custom Validation).
Common constraints
nullable() and optional()
.nullable() lets a present field hold null; .optional() lets it be omitted. These are field-presence modifiers rather than constraints — see Optional vs nullable.
constrain(Constraint<T> constraint, {String? message})
Applies a custom Constraint<T> that also implements Validator<T>. See the Custom Validation guide.
String constraints
Apply these to Ack.string() schemas.
minLength(int min)
Requires at least min characters.
Ack.string().minLength(5)maxLength(int max)
Requires at most max characters.
Ack.string().maxLength(100)length(int n)
Requires exactly n characters.
Ack.string().length(10)notEmpty()
Requires a non-empty string. Equivalent to minLength(1).
Ack.string().notEmpty()matches(String pattern, {String? example, String? message})
Requires the string to match a regular expression pattern.
Patterns are not automatically anchored. The pattern matches if found anywhere in the string. To require a full-string match, add anchors: ^...$
// Simple alphanumeric pattern (full-string match with anchors)
Ack.string().matches(r'^[a-zA-Z0-9]+$')
// UUID pattern (full-string match with anchors)
Ack.string()
.matches(r'^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$')
// Without anchors - matches substring (usually not what you want!)
Ack.string().matches(r'[0-9]+') // Matches "abc123xyz" ⚠️contains(String pattern, {String? example, String? message})
Requires pattern to appear somewhere in the string.
// Password must contain at least one uppercase letter
Ack.string().contains(r'[A-Z]')
// Password must contain at least one digit
Ack.string().contains(r'[0-9]')email()
Requires a valid email address format.
Ack.string().email()date()
Requires a valid date string in YYYY-MM-DD format.
Ack.string().date()datetime()
Requires a valid ISO 8601 date-time string with a timezone. Announced RFC 3339
leap seconds are accepted and preserved because this schema returns the input
String. The Ack.datetime() codec rejects leap seconds because Dart’s
DateTime cannot represent them without normalization.
Ack.string().datetime()time()
Requires a valid time string in HH:MM:SS format.
Ack.string().time()uri()
Requires a valid absolute URI with a scheme and host. This is the network-URI subset Ack accepts, rather than every relative or non-host URI permitted by RFC 3986.
Ack.string().uri()uuid()
Requires a valid UUID per RFC 4122.
Ack.string().uuid()ipv4()
Requires a valid IPv4 address.
Ack.string().ipv4()ipv6()
Requires a valid IPv6 address.
Ack.string().ipv6()Ack.enumString(List<String> allowedValues)
An Ack factory (not a fluent method) that creates a StringSchema accepting only values in allowedValues. Use for ad-hoc string lists; prefer Ack.enumValues(MyEnum.values) when a Dart enum exists.
Ack.enumString(['active', 'inactive', 'pending'])Ack.literal(String value)
An Ack factory (not a fluent method) that creates a StringSchema requiring an exact string match.
Ack.literal('admin')startsWith(String prefix)
Requires the string to start with prefix.
Ack.string().startsWith('https://')endsWith(String suffix)
Requires the string to end with suffix.
Ack.string().endsWith('.dart')url()
Alias for uri(). Requires a valid URL.
Ack.string().url()ip({int? version})
Requires a valid IP address. Set version to 4 or 6 to restrict the version.
Ack.string().ip() // Any IP (v4 or v6)
Ack.string().ip(version: 4) // IPv4 only
Ack.string().ip(version: 6) // IPv6 onlyString normalizers
These methods live directly on StringSchema and normalize the string in
declaration order alongside constraints during both parse and encode.
Because they return StringSchema, you can continue chaining string
constraints (Ack.string().trim().minLength(2)), use them inside @Schemable()
models, and export them to JSON Schema as type: 'string' without
'x-transformed': true.
trim()
Removes leading and trailing whitespace on parse and encode.
Ack.string().trim().minLength(2)
// " hello " → "hello"toLowerCase()
Converts the string to lowercase on parse and encode.
Ack.string().toLowerCase()
// "HELLO" → "hello"toUpperCase()
Converts the string to uppercase on parse and encode.
Ack.string().toUpperCase()
// "hello" → "HELLO"Number constraints
Apply these to Ack.integer(), Ack.double(), or Ack.number() schemas.
min(num limit)
Requires a value >= limit (inclusive).
Ack.integer().min(0) // >= 0
Ack.double().min(0.0) // >= 0.0
Ack.number().min(0) // >= 0max(num limit)
Requires a value <= limit (inclusive).
Ack.integer().max(100) // <= 100
Ack.double().max(100.0) // <= 100.0
Ack.number().max(100) // <= 100greaterThan(num limit)
Requires a value strictly > limit (exclusive).
Ack.integer().greaterThan(0) // > 0
Ack.double().greaterThan(0.0) // > 0.0
Ack.number().greaterThan(0) // > 0lessThan(num limit)
Requires a value strictly < limit (exclusive).
Ack.integer().lessThan(100) // < 100
Ack.double().lessThan(100.0) // < 100.0
Ack.number().lessThan(100) // < 100multipleOf(num factor)
Requires a value that is a multiple of factor. Integer checks are exact; doubles use a small scale-relative tolerance, so round accumulated floating-point sums (or validate integer units such as cents) before parsing.
Ack.integer().multipleOf(5) // Must be divisible by 5
Ack.double().multipleOf(0.5) // Use factors that avoid floating point rounding issues
Ack.number().multipleOf(0.5)positive()
Requires a value greater than 0.
Ack.integer().positive() // > 0
Ack.double().positive() // > 0.0
Ack.number().positive() // > 0negative()
Requires a value less than 0.
Ack.integer().negative() // < 0
Ack.double().negative() // < 0.0
Ack.number().negative() // < 0safe() (integer only)
Requires an integer within JavaScript’s safe range (-2^53+1 to 2^53-1).
Ack.integer().safe()finite()
Requires a finite number (rejects infinity and NaN). Ack.double() and
Ack.number() enforce this by default; finite() is available for
explicitness and API symmetry.
Ack.double().finite()
Ack.number().finite()List constraints
Apply these to Ack.list() schemas.
minLength(int min)
Requires at least min items.
Ack.list(Ack.string()).minLength(1)maxLength(int max)
Requires at most max items.
Ack.list(Ack.integer()).maxLength(10)length(int count)
Requires exactly count items.
Ack.list(Ack.boolean()).length(5)notEmpty()
Requires a non-empty list. Equivalent to minLength(1).
Ack.list(Ack.object({})).notEmpty()unique()
Requires all items to be unique. Uses deep structural equality, so nested maps and lists are compared by value.
Ack.list(Ack.string()).unique()Primitive inputs and numeric normalization
String and boolean schemas require the expected Dart runtime type. Numeric
schemas require a num, but normalize by mathematical value so native and web
builds behave identically. Non-numeric inputs surface as a TypeMismatchError
rather than being silently coerced.
| Schema | Accepted boundary value | Runtime value |
|---|---|---|
Ack.string() | String | unchanged String |
Ack.integer() | finite num with no fractional part, lossless | normalized int |
Ack.double() | finite num, exactly representable as double | normalized double |
Ack.number() | finite num | original int or double |
Ack.boolean() | bool | unchanged bool |
final stringSchema = Ack.string();
stringSchema.safeParse('hello'); // ✅ OK
stringSchema.safeParse(123); // ❌ FAIL: TypeMismatchError
stringSchema.safeParse(true); // ❌ FAIL: TypeMismatchError
final intSchema = Ack.integer();
intSchema.parse(42); // => 42 (int)
intSchema.parse(42.0); // => 42 (int)
intSchema.safeParse(42.5); // ❌ FAIL: not a mathematical integer
intSchema.safeParse('42'); // ❌ FAIL: TypeMismatchError
final doubleSchema = Ack.double();
doubleSchema.parse(3.14); // => 3.14 (double)
doubleSchema.parse(42); // => 42.0 (double)
final numberSchema = Ack.number();
numberSchema.safeParse(42); // ✅ OK (int is num)
numberSchema.safeParse(3.14); // ✅ OK (double is num)
numberSchema.safeParse('42'); // ❌ FAIL: TypeMismatchErrorAck.integer() and Ack.double() overlap for integral values. Ack.anyOf
returns the first successful branch, so order numeric branches according to the
runtime representation you want. Use Ack.number() when validation should
preserve an input that is already an int or double. Use transform/codec
when the boundary value is not already a num (for example, a numeric string).
Primitive type checking still lets unions distinguish the string "42" from
the numeric value 42 without configuration:
final stringOrNumber = Ack.anyOf([
Ack.string(),
Ack.integer(),
]);
stringOrNumber.safeParse('42'); // ✅ Matches string branch
stringOrNumber.safeParse(42); // ✅ Matches integer branchConverting boundary types
When your boundary payload uses a different shape than your runtime model (for example, ISO strings → DateTime, or "true"/"false" → bool), express the conversion explicitly with transform or a codec:
// Boundary "true"/"false" string → runtime bool
final boolFromString = Ack.enumString(['true', 'false'])
.transform((s) => s == 'true');
boolFromString.safeParse('true'); // ✅ runtime value: true
boolFromString.safeParse('false'); // ✅ runtime value: false
boolFromString.safeParse(true); // ❌ FAIL: string schema rejects boolUse schema.codec<R>(decode: ..., encode: ...) when you also need a reversible encode path back to the boundary type.
Combining constraints
You can chain multiple constraints. Ack evaluates them in the order you apply them.
final usernameSchema = Ack.string()
.minLength(3) // First: check min length
.maxLength(20) // Second: check max length
.matches(r'^[a-z0-9_]+$') // Third: require only lowercase letters, digits, or underscores
.notEmpty(); // Redundant if minLength(>0) is used, but illustrates chaining
final quantitySchema = Ack.integer()
.min(1) // Must be at least 1
.max(100) // Must be at most 100
.multipleOf(1); // Must be an integer (redundant for Ack.integer)Next steps
- Error handling: Handle and display validation errors
- Custom validation: Create custom constraints and refinement logic
- Schema types: All available schema types and their operations
- Common recipes: Practical validation patterns and solutions
- Flutter forms: Integrate validation with Flutter form widgets