API Reference

This page provides a quick reference for the core Ack classes, methods, and annotations. For detailed explanations and usage examples, refer to the specific guides linked below.

Core Ack Class

Entry point for creating schemas. See Schema Types.

• Ack.string(): Creates a StringSchema for validating String values.
• Ack.integer(): Creates an IntegerSchema for validating int values. Rejects double (e.g. 42.0).
• Ack.double(): Creates a DoubleSchema for validating double values. Rejects int (e.g. 42).
• Ack.number(): Creates a NumberSchema for validating any num value (accepts both int and double).
• Ack.boolean(): Creates a BooleanSchema for validating bool values.
• Ack.list(AckSchema itemSchema): Creates a ListSchema for validating arrays. Nullable item schemas are not supported; make the list itself nullable instead.
• Ack.object(Map<String, AckSchema> properties): Creates an ObjectSchema for validating objects.
• Ack.enumValues(List<T> values): Creates an EnumSchema<T> for Dart enum types. Accepts enum instances, string names, or indices. Preferred over enumString when a Dart enum exists.
• Ack.enumCodec(List<T> values): Like enumValues, but returns a CodecSchema<String, T> instead of an EnumSchema<T>. Use this when downstream code expects every value-shape to be a CodecSchema (e.g. a registry of codecs). The decode and encode functions are identity — the underlying EnumSchema still maps between T and the enum's .name.
• Ack.enumString(List<String> values): Creates a StringSchema constrained to the given values. For ad-hoc string lists without a backing Dart enum.
• Ack.anyOf(List<AckSchema> schemas): Creates an AnyOfSchema for union types.
• Ack.any(): Creates an AnySchema that accepts any non-null JSON-safe value. Chain .nullable() to allow null.
• Ack.lazy(String name, AckSchema Function() builder): Creates a memoized deferred schema reference for recursive schema graphs. JSON Schema export renders Draft-7 definitions / $ref entries using name.
• Ack.discriminated<T extends Object>(...): Creates a discriminated union schema. Branches may be plain ObjectSchema or transformed schemas whose base is an ObjectSchema. The union owns the discriminator: branches normally omit it, boundary payloads must include it, compatible branch discriminator fields are allowed, and conflicts are rejected. Exported/generated branches expose the exact branch literal.

AckSchema<Boundary, Runtime> (Base Class)

Base class for all schema types.

Primary Validation Methods

• SchemaResult<Runtime> safeParse(Object? data, {String? debugName}): Validates the input data and returns a result. Never throws exceptions - returns SchemaResult with either success or failure. Use safeParse(...).getOrNull() to obtain the validated value with no exception.
• Runtime? parse(Object? data, {String? debugName}): Validates the input data and returns the value. Throws AckException if validation fails.
• SchemaResult<TOut> safeParseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName}): Parses and maps the validated value to another type.
• TOut parseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName}): Throwing variant of safeParseAs.
• SchemaResult<Boundary> safeEncode(Runtime? value, {String? debugName}): Encodes a runtime value back to the boundary representation.
• Boundary? encode(Runtime? value, {String? debugName}): Throwing variant of safeEncode.

Schema Modification Methods

• AckSchema<Boundary, Runtime> nullable({bool value = true}): Returns a new schema that also accepts null values.
• AckSchema<Boundary, Runtime> optional({bool value = true}): Returns a new schema marked as optional (for object fields).
• AckSchema<Boundary, Runtime> describe(String description): Adds a description for documentation and JSON Schema generation.
• DefaultSchema<Boundary, Runtime> withDefault(Runtime value): Wraps the schema in a DefaultSchema that supplies value when the parse input is null.

Primitive schemas (StringSchema, IntegerSchema, DoubleSchema, NumberSchema, BooleanSchema) are strict — they reject values whose Dart runtime type doesn't match. IntegerSchema and DoubleSchema do not overlap (42.0 fails Ack.integer(), 42 fails Ack.double()); use Ack.number() when either is acceptable. For non-num boundary types (e.g. numeric strings), use transform or codec to convert before validation.

Custom Validation Methods

• AckSchema<Boundary, Runtime> constrain(Constraint<Runtime> constraint, {String? message}): Applies a custom validation constraint.
• AckSchema<Boundary, Runtime> withConstraint(Constraint<Runtime> constraint): Applies a custom validation constraint (alias for constrain).
• AckSchema<Boundary, Runtime> refine(bool Function(Runtime) validate, {String message}): Adds custom validation logic with an optional custom error message.
• CodecSchema<Boundary, R> transform<R>(R Function(Runtime) transformer): Transforms validated runtime values to a different type.

Utility Methods

• Map<String, Object?> toJsonSchema(): Renders generic Draft-7 JSON Schema through the canonical AckSchemaModel boundary.
• Map<String, Object?> toMap(): Serializes the schema for debugging.

See also Schema Types for detailed usage examples.

StringSchema

Schema for validating strings. See String Validation.

Length Constraints

• minLength(int min): Minimum string length
• maxLength(int max): Maximum string length
• length(int exact): Exact string length
• notEmpty(): String must not be empty (equivalent to minLength(1))

Pattern Matching

• matches(String pattern, {String? example, String? message}): Must match regex pattern. Note: Patterns are NOT automatically anchored - use ^...$ for full-string matching. See String Validation for details.
• contains(String pattern, {String? example, String? message}): Must contain pattern anywhere in string (partial matching)
• startsWith(String value): Must start with specified value
• endsWith(String value): Must end with specified value

Format Validation

• email(): Must be valid email format
• url(): Must be valid URL format (alias for uri())
• uri(): Must be valid URI according to RFC 3986
• uuid(): Must be valid UUID format
• ip({int? version}): Must be valid IP address (version 4 or 6)
• ipv4(): Must be valid IPv4 address
• ipv6(): Must be valid IPv6 address

Date and Time

• date(): Must be valid ISO 8601 date (YYYY-MM-DD)
• datetime(): Must be valid ISO 8601 datetime
• time(): Must be valid time format (HH:MM:SS)

Value Restrictions

• literal(String value): Must exactly match the given value
• enumString(List<String> values): Must be one of the specified values

Transformations

• trim(): Removes leading and trailing whitespace
• toLowerCase(): Converts to lowercase
• toUpperCase(): Converts to uppercase

IntegerSchema / DoubleSchema / NumberSchema (Number Schemas)

Schemas for validating numeric values. IntegerSchema only accepts int, DoubleSchema only accepts double, and NumberSchema accepts any num (either int or double). DoubleSchema and NumberSchema reject non-finite values by default. See Number Validation.

• min(num limit): Minimum value (inclusive)
• max(num limit): Maximum value (inclusive)
• greaterThan(num limit): Must be greater than limit (exclusive)
• lessThan(num limit): Must be less than limit (exclusive)
• positive(): Must be greater than 0
• negative(): Must be less than 0
• multipleOf(num factor): Must be a multiple of the factor
• finite(): Must be finite (DoubleSchema and NumberSchema; already the default)
• safe(): Must be within safe integer range (IntegerSchema only)

BooleanSchema

Schema for validating booleans. Validates true and false values strictly — non-boolean inputs are rejected. For boundary types that arrive as strings (e.g. "true"/"false"), use a transform or codec to convert before validation.

ListSchema<T>

Schema for validating arrays. See List Validation.

• minItems(int min): Minimum number of items (alias: minLength)
• maxItems(int max): Maximum number of items (alias: maxLength)
• exactLength(int exact): Exact number of items (alias: length)
• nonEmpty(): List must have at least one item (alias: notEmpty)
• unique(): All items must be unique

ObjectSchema

Schema for validating objects (maps). See Object Validation.

• Constructed using Ack.object(Map<String, AckSchema> properties, {bool additionalProperties = false}).
• Use .pick(List<String> keys) to create schema with only specified properties.
• Use .omit(List<String> keys) to create schema excluding specified properties.
• Use .extend(Map<String, AckSchema> newProperties) to add more properties.
• Use .partial() to make all properties optional.
• Use .strict() to disallow additional properties.
• Use .passthrough() to allow additional properties not defined in the schema.
• Use .merge(ObjectSchema other) to combine with another object schema.

SchemaResult<T>

Object returned by safeParse(). See Error Handling.

• bool isOk: True if validation succeeded
• bool isFail: True if validation failed
• T? getOrThrow(): Returns the validated value (nullable for nullable schemas) or throws an exception
• T? getOrNull(): Returns the validated value or null if validation failed
• SchemaError getError(): Returns the validation error (only valid when isFail is true)
• T? getOrElse(T? Function() orElse): Returns the validated value or the fallback result

SchemaError (and Subclasses)

Object representing a validation failure. See Error Handling.

• String message: Human-readable error message
• SchemaContext context: Context information about where the error occurred

Subclasses:

• SchemaConstraintsError: Constraint validation failures
• SchemaNestedError: Nested validation failures (for objects/arrays)
• SchemaValidationError: Custom refinement failures

Constraint<T>

Base class for creating custom validation rules. See Custom Validation.

• String constraintKey: Unique key for the constraint
• String description: Human-readable description
• Map<String, Object?> toMap(): Serializes the constraint for debugging

Validator<T> (Mixin)

Validation behavior mixin used with Constraint<T>.

• bool isValid(T value): Returns true when the value passes validation
• String buildMessage(T value): Builds the validation failure message
• ConstraintError? validate(T value): Validates a value and returns an error if invalid

Additional Schema Types

Ack ships with a broad set of schema factories beyond what is listed here. See Schema Types for the full catalogue, including helpers like Ack.date(), Ack.literal(), and rich list/object combinators.

Ack.discriminated(...)

Schema for polymorphic validation based on a string discriminator property.

• Branch schemas normally omit the discriminator field.
• The boundary payload must still contain the discriminator key.
• If a branch schema includes the discriminator field, it must be Ack.literal(...) matching the branch key or Ack.enumString(...) containing it. Broad, transformed, refined, or otherwise restrictive discriminator fields are rejected.
• Exported and generated schemas expose each branch discriminator as an exact literal.
• Generated subtype parse() and safeParse() methods validate through the union's effective branch.

Ack.lazy(...)

Schema reference for recursive object graphs.

• Created using Ack.lazy<Boundary, Runtime>(name, builder).
• The builder is resolved once and memoized.
• toJsonSchema() and toSchemaModel() export Draft-7 definitions / $ref entries using the lazy name.
• Bare or wrapped lazy schemas cannot be used as discriminated-union branches because the branch discriminator must be analyzable at construction time.

Code Generation Annotations

Use the ack_generator builder to turn annotations into extension types. After adding the annotations below, run:

dart run build_runner build

@AckType()

Target: Schema variables and getters

Generates: An extension type wrapper around the existing schema

Annotate an existing schema variable or getter to generate an extension type wrapper. The schema itself stays in your source file.

Supported schema types:

• Ack.object({...}) → Object extension types
• Primitives: Ack.string(), Ack.integer(), Ack.double(), Ack.boolean()
• Collections: Ack.list(...)
• Enums: Ack.literal(), Ack.enumString(), Ack.enumValues()
• Discriminated unions: Ack.discriminated(...)

Unsupported: Ack.any(), Ack.anyOf()

For Ack.discriminated(...) constraints with @AckType, see Type-safe Schemas.

Example:

@AckType()
final userSchema = Ack.object({
  'name': Ack.string(),
  'email': Ack.string().email(),
});

// Generated:
// - extension type UserType(Map<String, Object?> _data) { ... }
// - The schema variable remains unchanged

// Usage:
final user = UserType.parse({'name': 'Alice', 'email': 'alice@example.com'});
print(user.name);  // Type-safe String access
print(user.email); // Type-safe String access

EnumSchema<T>

Schema for validating enum values.

• Created using Ack.enumValues(List<T> values) where T extends Enum

AnyOfSchema

Schema for union types (value must match one of several schemas).

• Created using Ack.anyOf(List<AckSchema> schemas)

DiscriminatedObjectSchema

Schema for polymorphic validation based on a discriminator field.

• Created using Ack.discriminated<T extends Object>(...) with discriminatorKey and schemas.
• effectiveBranch(String discriminatorValue): Returns the branch schema with the discriminator injected as the exact branch literal. Generated subtypes use this to validate a specific branch.

AckSchemaModel

Canonical export model for Ack schemas.

• Created using schema.toSchemaModel()
• Represents the boundary/export shape, JSON-compatible defaults, discriminator metadata, target-independent constraints, and export warnings
• Render generic Draft-7 JSON Schema with schema.toSchemaModel().toJsonSchema(), the same output returned by schema.toJsonSchema()
• Adapter packages that need a JSON map can call schema.toJsonSchema(); adapters for non-JSON targets should convert from AckSchemaModel rather than traversing AckSchema subclasses directly

AnySchema

Schema that accepts any non-null JSON-safe value without validation.

• Created using Ack.any()
• Useful for dynamic payloads or pass-through metadata

CodecSchema<Boundary, Runtime>

Schema that decodes boundary values into runtime values and encodes runtime values back to the boundary representation.

• Created using schema.transform<R>(R Function(Runtime) transformer) or schema.codec<R>(decode: ..., encode: ...)

Optional Schemas

Every schema can be marked optional through the optional({bool value = true}) fluent API.

• Calling schema.optional() sets isOptional to true without wrapping the schema.
• Use schema.optional(value: false) to clear the optional flag.
• Optional affects object-field presence only; combine with .nullable() to also allow explicit null.

Refer to the Schema Types guide for detailed usage and examples.