Configuration

Ack has no global configuration object. All behavior is configured at the schema level through the fluent API.

Schema-level configuration

Define behavior when you create your schemas.

Optional and nullable values

Fields in Ack.object are required and non-nullable by default. Use .optional() when a field may be omitted, .nullable() when a present field may be null, or both when either state is valid.


Ack.object({
  'id': Ack.integer(),
  'nickname': Ack.string().optional(),
  'middleName': Ack.string().nullable(),
  'avatarUrl': Ack.string().url().optional().nullable(),
});

See Optional vs nullable for the complete presence and nullability matrix.

Additional properties

Control how extra fields are handled with the additionalProperties parameter in Ack.object.


// Reject extra properties (default)
Ack.object({'id': Ack.integer()});
// or explicitly:
Ack.object({'id': Ack.integer()}, additionalProperties: false);
 
// Allow extra properties
Ack.object({'id': Ack.integer()}, additionalProperties: true);

Use strict objects for data you own and want to detect drift in. At external API boundaries, additionalProperties: true can make a schema resilient to new response fields while still validating every field your application uses.

Default values

Use .withDefault(value) when a null or missing object field should receive a runtime value during parsing. The default must satisfy the schema’s runtime type and constraints.


final settingsSchema = Ack.object({
  'theme': Ack.enumString(['light', 'dark']).withDefault('light'),
  'pageSize': Ack.integer().min(1).max(100).withDefault(20),
});

Defaults change the parsed result; .optional() only changes whether an object field is required.

Schema metadata

Attach a description with .describe() when the schema is also used for JSON Schema export or adapter packages.


final userIdSchema = Ack.string()
    .uuid()
    .describe('Stable identifier for a user account');

Custom error messages

Built-in constraints provide default messages. APIs that accept message:, such as .matches(), can replace that message inline. Use .constrain() to provide a message for a reusable custom constraint. See Custom error messages.


final usernameSchema = Ack.string().matches(
  r'^[a-z0-9_]+$',
  message: 'Use lowercase letters, numbers, and underscores only.',
);

Custom validation logic

Use .constrain() for reusable value-level checks and .refine() for cross-field rules — see Custom Validation.

Code generation

Annotate a top-level schema with @AckType() to generate a typed wrapper — see TypeSafe Schemas for setup and supported shapes.

Schema Types — factories, composition, and transformations
Validation Rules — built-in constraints
Codecs — bidirectional boundary/runtime configuration
JSON Schema Integration — exported metadata and defaults