Skip to Content
DocsAckAdvancedConfiguration

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 missing object field should receive a runtime value during parsing. The default must satisfy the schema’s runtime type and constraints, and it exports as the JSON Schema default. A present null is a value, not a missing key: it fails unless the field is also nullable, in which case .nullable().withDefault(value) parses it as the default too. Parsing null with a withDefault schema directly returns the default.

final settingsSchema = Ack.object({ 'theme': Ack.enumString(['light', 'dark']).withDefault('light'), 'pageSize': Ack.integer().min(1).max(100).withDefault(20), });
settingsSchema.parse({}); // {'theme': 'light', 'pageSize': 20} settingsSchema.safeParse({'theme': null}); // fails: theme is not nullable

During object encoding, both a missing defaulted field and a field holding null encode as the validated default, through the field’s encoder. A nullable field without a default still encodes as null. These default/null rules are breaking changes in 2.0.0-beta.2.

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 @Schemable() to generate an immutable model, or annotate a hand-written class with @Schemable() to generate its schema. See Model Code Generation for both workflows.

Last updated on