Configuration
Ack allows for some configuration settings, although most behavior is controlled directly through the schema definitions when they are created.
Global Settings (Less Common)
In general, Ack prefers configuration per schema definition rather than global settings. However, if needed, you might manage global aspects like custom format registries or shared validation logic through your own application structure (e.g., a singleton or dependency injection).
Currently, Ack does not expose a dedicated global configuration object. Configuration is primarily done at the schema level.
Schema-Level Configuration
Most "configuration" happens when you define your schemas using the fluent API provided by Ack.
Required Fields
Use the required parameter in Ack.object to specify mandatory fields within an object.
Ack.object({
'id': Ack.int,
'name': Ack.string,
'email': Ack.string.email().nullable() // Email is optional because nullable
}, required: ['id', 'name']); // id and name are required
Additional Properties
Control how extra fields (not defined in the schema) are handled using the additionalProperties parameter in Ack.object.
// Allow any extra properties (default behavior)
Ack.object({
'id': Ack.int
}, additionalProperties: true);
// or simply:
Ack.object({
'id': Ack.int
});
// Disallow any extra properties
Ack.object({
'id': Ack.int
}, additionalProperties: false);
Custom Error Messages
Built-in validation rules provide default error messages. For custom error messages, use custom constraints with the .constrain() method.
See also: Custom Error Messages in Error Handling.
// Built-in constraints use default messages
Ack.string.minLength(5); // Default: "Too short, min 5 characters"
Ack.int.min(18); // Default: "Must be at least 18"
// For custom messages, use custom constraints (see Custom Validation section below)
Custom Validation Logic
Use .constrain() to add complex or reusable validation logic.
class IsPositiveConstraint extends Constraint<double> with Validator<double> {
const IsPositiveConstraint() : super(
constraintKey: 'is_positive',
description: 'Number must be positive'
);
@override
bool isValid(double value) {
return value > 0;
}
@override
String buildMessage(double value) => 'Number must be positive';
}
// Apply the custom constraint
Ack.double.constrain(IsPositiveConstraint());
See the Custom Validation Guide for details.
Code Generation Configuration
When using ack_generator, you configure schema generation via annotations on your model classes.
@Schema Annotation
This class-level annotation controls overall schema generation for a model.
@Schema(
// Add a description to the generated schema (useful for JSON Schema)
description: 'User account information',
// Allow properties not defined in the model?
additionalProperties: true,
// If true, which field in the model stores these extra properties?
additionalPropertiesField: 'metadata',
// Optionally override the generated schema class name
schemaClassName: 'MyUserSchema'
)
class User {
// ... fields ...
final Map<String, dynamic> metadata; // Matches additionalPropertiesField
}
Property Annotations
Validation rules are configured using annotations on model fields.
@Schema()
class Product {
@MinLength(3, message: "Name too short")
@Required() // Make this nullable String required
final String? name;
@Min(0, exclusive: true) // Price must be > 0
@Description("The retail price of the product")
final double price;
// ... rest of the model ...
}
See the Code Generation Guide for a list of available annotations.
Summary
- Ack primarily uses schema-level configuration through methods and parameters like
.minLength(),required: [...],additionalProperties: .... - Code generation is configured using
@Schema()and property annotations. - There is currently no central global configuration object provided by Ack itself.