What’s New & Migration Guide
This guide summarizes what exists in Ack today, what changed in 1.7 and 2.0 (and why), and every removed 1.x symbol with its exact substitution.
Beta.2 to beta.3: Is…/Has… rule annotations
2.0.0-beta.3 replaces the Validate namespace with top-level rule
annotations. Is… names what a value is; Has… names a bound or property it
has:
@Schemable()
final class const Account({
@HasMinLength(2) required final String name,
@IsEmail() required final String email,
}) with _$AccountAck {
static final schema = AccountSchema.schema;
static final fromJson = AccountSchema.fromJson;
}Each old constructor still works and generates the same code, but it is
deprecated and its warning names the replacement. Validate is removed
before Ack 2.0.0. Use the
validation annotation table to rename every use;
ipv4() and ipv6() become @IsIp(version: 4) and @IsIp(version: 6).
@Schemable and @AckKey keep their names, and the fluent API
(Ack.string().minLength(3)) is unchanged.
Class-first examples now attach the generated facade with
static final schema = AccountSchema.schema; instead of naming the private
codec variable. Both forms generate the same code, so existing classes keep
working.
Dart 3.13 and primary constructors
2.0.0-beta.3 requires Dart >=3.13.0, and Flutter >=3.47.0 (the first
release that bundles Dart 3.13.0). Apps on Flutter 3.41 to 3.46 must upgrade
Flutter to use Ack 2.0. Class-first examples now use Dart 3.13 primary
constructors, with the rule annotations and @AckKey on the declaring
parameters, as in the Account example above. A classic constructor with
annotated fields still works and generates identical code, so existing models
need no change.
Beta.1 to beta.2: defaults and explicit null
These are breaking changes in 2.0.0-beta.2:
Ack.object({'role': Ack.string().withDefault('member')})parses{}as{'role': 'member'}, but rejects{'role': null}. Add.nullable()before.withDefault('member')to accept a present null and parse it as the default. Calling the defaulted schema’sparse(null)directly still uses the default.- Object encoding substitutes the validated default for a missing or null
defaulted property. A nullable defaulted model constructed with
label: nullnow encodes its non-null default. A nullable field without a default keeps its existing null behavior. - Generated fields follow Dart nullability:
Trejects explicit JSON null;T?accepts it unless marked@IsNotNull(). Constructor defaults fill missing keys and follow the same encoding rules as object schemas.
Regenerate model parts after updating ack and ack_generator together to
beta.2.
1. What Exists in Ack
Ack is organized into five coordinated packages that share one version number and one canonical schema representation (AckSchema<Boundary, Runtime>):
| Package | Role | Key Capabilities |
|---|---|---|
ack | Core runtime & annotations | • Fluent schema builders: Ack.string(), Ack.integer(), Ack.double(), Ack.number(), Ack.boolean(), Ack.list(), Ack.map(), Ack.object(), Ack.any(), Ack.literal(), Ack.enumString(), Ack.enumValues(), Ack.anyOf(), Ack.discriminated(), Ack.lazy()• Bidirectional CodecSchema<Boundary, Runtime>: Ack.date(), Ack.datetime(), Ack.uri(), Ack.duration(), .codec(), .transform()• Two-way string normalizers: .trim(), .toLowerCase(), .toUpperCase()• JsonMaybe<T> (JsonAbsent<T> / JsonValue<T>) for tri-state PATCH payloads• JSON Schema Draft 2020-12 import and runtime validation ( Ack.fromJsonSchema()); native schemas export Draft-7, while toJsonSchema() preserves imported 2020-12 resources (toJsonSchemaDraft7() explicitly lowers them)• Sealed SchemaResult<T> (Ok / Fail) and sealed SchemaError hierarchy• Unified codegen annotations in package:ack/ack.dart: @Schemable(), @AckKey(), and the Is…/Has… rule annotations (@IsRequired(), @HasMinLength(n), @IsEmail(), …) |
ack_generator | Two-way code generator | • Schema-first (@Schemable() on a top-level schema): Generates an immutable model class, Model.schema, parse/safeParse, fromJson/toJson/safeToJson, typed copyWith, and deep ==/hashCode in <file>.g.dart• Class-first ( @Schemable() on a final class or sealed class): Supports standard and Dart 3.13+ primary constructors; generates the <Name>Schema facade and the _$<Name>Ack mixin in <file>.g.dart• .schema.json codegen (ack_generator:ack_json_schema): Compiles lib/**/*.schema.json assets into <name>.schema.dart + <name>.schema.g.dart |
ack_mcp_dart | MCP tool input adapter | • server.registerAckTool(name, input: schema, callback: ...), schema.toMcpToolInputSchema(), and parseMcpToolArguments(...); callbacks return CallToolResult and own output validation |
ack_firebase_ai | Firebase AI (Gemini) adapter | • schema.toFirebaseAiResponseJsonSchema() for the map-based GenerationConfig.responseJsonSchema field |
ack_json_schema_builder | json_schema_builder bridge | • Bidirectional schema.toJsonSchemaBuilder() and jsbSchema.toAckSchema() |
2. What Changed & Why
| Change | Introduced | What Changed | Why It Changed |
|---|---|---|---|
Annotations merged into package:ack | 1.7.0 | ack_annotations was retired and model/validation annotations moved into ack. In 2.0, the public annotation API is @Schemable(), @AckKey(), and the Is…/Has… rule annotations from package:ack/ack.dart. | Eliminated version skew between ack and a separate annotations package and reduced model files to a single import 'package:ack/ack.dart';. |
Unified @Schemable() annotation | 1.7.0 | @Schemable() drives both schema-first and class-first generation, replacing @AckInfer(), @AckModel(), and @AckType(). | One annotation and one mental model whether you start from an AckSchema or a hand-written Dart class. |
Is…/Has… rule annotations | 2.0.0-beta.3 | Field and parameter rules—presence (@IsRequired(), @IsOptional()), nullability (@IsNotNull()), bounds (@HasMin(0)), formats (@IsEmail(), @IsDateTime(), @IsUri()), and collection rules (@IsNotEmpty(), @HasUniqueItems())—are top-level classes in package:ack/ack.dart. The 2.0 beta Validate namespace is deprecated and is removed before Ack 2.0.0. | Top-level 1.x classes (@Required, @Email, @Uuid, @Date, @Uri, @DateTime, @Pattern) collided with package:meta / Flutter (Required), dart:core (Uri, DateTime, Pattern), and package:uuid, forcing import prefixes (as ack). The beta Validate namespace avoided that with a prefix on every use. The Is…/Has… names need neither: none of them collides with the Dart SDK, Flutter, or common packages. |
Single .g.dart part & direct JSON emitter | 2.0.0 | ack_generator:ack_generator is a SharedPartBuilder that emits <file>.g.dart directly with no json_serializable or json_annotation dependency. | In 1.x, every model required two part directives (.ack.dart + .ack.g.dart) and a second json_serializable pass. Direct emission cuts build steps in half, uses standard part '<file>.g.dart';, and coexists with Freezed or Riverpod in the same file. |
Layered custom schema resolution (T.schema, schemas: [...]) | 1.7.0 / 2.0.0 | Custom field types resolve via @Schemable(schemas: [...]) (on classes, unions, or library; directives), type-owned T.schema / T.schema<A>() factories, or automatic detection of a unique top-level AckSchema<Boundary, T> in the current library. | Removed per-field @AckField(schema: ...) boilerplate on every field that uses a domain value object, extension type, enum, or generic wrapper. |
Typed $ClassCopyWith<Class> getter | 1.7.0 | model.copyWith returns a typed callable interface instead of widening parameters to Object?. | Passing model.copyWith(age: 'wrong') previously compiled and failed only at runtime (TypeError). Now mistyped arguments fail at compile time while model.copyWith(age: null) still clears nullable fields. |
Two-way string normalizers (.trim(), .toLowerCase(), .toUpperCase()) | 2.0.0 | Normalizers live directly on StringSchema and run in declaration order alongside constraints during both parse and encode. | In 1.x, .trim() used a one-way .transform(), which failed on encode(), was rejected by @Schemable(), and emitted 'x-transformed': true in JSON Schema. |
JsonMaybe<T> (JsonAbsent / JsonValue<T>) | 2.0.0 | Tri-state field container for class-first @Schemable() models. | A plain String? field in Dart cannot distinguish {"bio": null} (clear field in a PATCH request) from {} (leave field unchanged) when encoding back to JSON. |
Sealed SchemaError & AckSchema hierarchies + decoder Error propagation | 2.0.0 | SchemaError and AckSchema are sealed classes. CodecSchema rethrows programmer Errors (TypeError, StateError) on parse/safeParse and catches only Exceptions as SchemaTransformError. | Enables exhaustive switch (error) pattern matching without a wildcard branch, and prevents programming bugs inside decode callbacks from being masked as user input errors. |
JSON Schema Draft 2020-12 default + .schema.json codegen | 2.0.0 | Ack.fromJsonSchema() supports the full required Draft 2020-12 keyword suite ($dynamicRef, unevaluatedProperties, prefixItems, minContains/maxContains, dependentSchemas, patternProperties, and all 19 formats when assertFormats: true). toJsonSchema() preserves 2020-12 resources by default (toJsonSchemaDraft7() lowers to Draft-7). | Enables lossless round-tripping of modern protocol schemas (MCP, A2UI v0.9, OpenAPI 3.1) and compile-time Dart codegen from .schema.json files. |
ECMA-262 Unicode mode (u) for imported pattern | 1.7.0 | Imported JSON Schema pattern expressions compile with ECMA-262 Unicode semantics. | Required by the JSON Schema specification so . matches full Unicode code points (including emoji) and \p{...} property escapes work identically to Ajv. |
3. What Doesn’t Exist Anymore & Exact Substitutions
Packages & Imports
| Removed Item | Removed In | Exact Substitution |
|---|---|---|
ack_annotations package in pubspec.yaml | 1.7.0 | Remove ack_annotations; ack includes all annotations. |
import 'package:ack_annotations/ack_annotations.dart'; | 1.7.0 | import 'package:ack/ack.dart'; |
import 'package:ack_annotations/format_annotations.dart'; | 1.7.0 | import 'package:ack/ack.dart'; (use the rule annotations) |
import 'package:ack/format_annotations.dart'; | 2.0.0 | import 'package:ack/ack.dart'; (use @IsDateTime(), @IsUri(), @IsIp(), @IsIp(version: 4), @IsIp(version: 6)) |
json_serializable & json_annotation for @Schemable() models | 2.0.0 | Remove unless used by other non-Ack classes; ack_generator emits toJson / fromJson directly. |
Model & Field Annotations
| Removed Symbol | Removed In | Exact Substitution |
|---|---|---|
@AckType() | 2.0.0 | @Schemable() on the top-level schema |
@AckInfer(...) | 2.0.0 | @Schemable(...) on the top-level schema |
@AckModel(...) | 2.0.0 | @Schemable(...) on the class |
@Optional() / @AckField(presence: AckFieldPresence.optional) | 2.0.0 | @IsOptional() (add @IsNotNull() if present JSON value must not be null) |
@Required() / @AckField(presence: AckFieldPresence.required) | 2.0.0 | @IsRequired() |
@NotNull() | 2.0.0 | @IsNotNull() (rejects explicit null without requiring an optional key) |
@JsonKey(name: 'wire_name') on @Schemable fields | 2.0.0 | @AckKey('wire_name') |
@AckField(schema: ...) | 2.0.0 | @Schemable(schemas: [...]), T.schema, or top-level library schema |
@AckField(description: ...) | 2.0.0 | /// @description ... doc tag |
@JsonConverter() on @Schemable classes/fields | 1.7.0 (rejected) | Declare static final schema = ... on the type or register one in @Schemable(schemas: [...]) |
Validation Annotations
The top-level 1.x validation and presence classes were removed in 2.0.0.
The 2.0 beta Validate namespace is deprecated in 2.0.0-beta.3 and is
removed before Ack 2.0.0. Replace both with the rule annotations from
package:ack/ack.dart. Each rule keeps the same field types, generated schema,
and errors:
Removed 1.x annotation | Deprecated 2.0 beta annotation | Rule annotation (2.0.0-beta.3) |
|---|---|---|
@Optional() | @Validate.optional() | @IsOptional() |
@Required() | @Validate.required() | @IsRequired() |
@NotNull() | @Validate.notNull() | @IsNotNull() |
@Min(value) | @Validate.min(value) | @HasMin(value) |
@Max(value) | @Validate.max(value) | @HasMax(value) |
@MultipleOf(value) | @Validate.multipleOf(value) | @IsMultipleOf(value) |
@Positive() | @Validate.positive() | @IsPositive() |
@Negative() | @Validate.negative() | @IsNegative() |
@MinLength(n) | @Validate.minLength(n) | @HasMinLength(n) |
@MaxLength(n) | @Validate.maxLength(n) | @HasMaxLength(n) |
@Pattern(r'...') / @Matches(r'...') | @Validate.matches(r'...') | @HasMatch(r'...') (not anchored; use ^...$ for a full-string match) |
@NotEmpty() | @Validate.notEmpty() | @IsNotEmpty() (works on String, List, and Set) |
@Email() | @Validate.email() | @IsEmail() |
@Url() | @Validate.url() | @IsUrl() |
@Uri() | @Validate.uri() | @IsUri() |
@Uuid() | @Validate.uuid() | @IsUuid() |
@Date() | @Validate.date() | @IsDate() |
@DateTime() | @Validate.dateTime() | @IsDateTime() |
@Ip() | @Validate.ip() / @Validate.ip(version: v) | @IsIp() / @IsIp(version: v) |
@Ipv4() | @Validate.ipv4() | @IsIp(version: 4) |
@Ipv6() | @Validate.ipv6() | @IsIp(version: 6) |
@MinItems(n) | @Validate.minItems(n) | @HasMinItems(n) |
@MaxItems(n) | @Validate.maxItems(n) | @HasMaxItems(n) |
@UniqueItems() | @Validate.uniqueItems() | @HasUniqueItems() |
Generated Files, Builders & Runtime APIs
Removed 1.x Item | Removed In | Exact 2.0 Substitution |
|---|---|---|
part 'model.ack.dart'; + part 'model.ack.g.dart'; | 2.0.0 | Single part 'model.g.dart'; |
ack_generator|ack_models & ack_generator|ack_model_json in build.yaml | 2.0.0 | ack_generator:ack_generator (plus optional ack_generator:ack_json_schema for .schema.json files) |
@AckType() *Type extension type, .args, ModelType.parse(...) | 2.0.0 | Generated Model class with typed fields, Model.parse(...), Model.safeParse(...), Model.fromJson(...), model.toJson() |
Ack.enumCodec(MyEnum.values) | 2.0.0 | Ack.enumValues(MyEnum.values) |
schema.toMap() | 2.0.0 | schema.toJsonSchema() or schema.toSchemaModel() |
server.registerAckModelTool(...) (ack_mcp_dart) | 2.0.0 | server.registerAckTool(name, input: Model.schema, callback: ...); return a CallToolResult from the callback |
convertAckSchemaModelToBuilder(model) (ack_json_schema_builder) | 2.0.0 | schema.toJsonSchemaBuilder() |
Ack.fromJsonSchema(...) enforcing format by default | 2.0.0 | Pass Ack.fromJsonSchema(schema, assertFormats: true) (or declare format-assertion in $vocabulary) when format assertions are required |
schema.toJsonSchema() lowering imported 2020-12 schemas to Draft-7 | 2.0.0 | schema.toJsonSchema() now preserves Draft 2020-12 resources by default; call schema.toJsonSchemaDraft7() when Draft-7 lowering is required |
4. Before & After Migration Examples
Class-First Model Migration
// ❌ BEFORE (Ack 1.6)
import 'package:ack/ack.dart';
import 'package:ack_annotations/ack_annotations.dart' as ack;
import 'package:ack_annotations/format_annotations.dart' as formats;
import 'package:json_annotation/json_annotation.dart';
part 'account.ack.dart';
part 'account.ack.g.dart';
@ack.AckModel(caseStyle: ack.AckCaseStyle.snake)
final class Account with _$AccountAck {
const Account({required this.userName, required this.createdAt});
@JsonKey(name: 'username')
@ack.MinLength(3)
@ack.Pattern(r'^[a-z0-9_]+$')
final String userName;
@formats.DateTime()
final String createdAt;
}// ✅ AFTER (Ack 2.0)
import 'package:ack/ack.dart';
part 'account.g.dart';
@Schemable(caseStyle: AckCaseStyle.snake)
final class const Account({
@AckKey('username')
@HasMinLength(3)
@HasMatch(r'^[a-z0-9_]+$')
required final String userName,
@IsDateTime() required final String createdAt,
}) with _$AccountAck {
static final schema = AccountSchema.schema;
static final fromJson = AccountSchema.fromJson;
}Schema-First Model Migration
// ❌ BEFORE (Ack 1.6, @AckInfer)
import 'package:ack/ack.dart';
import 'package:ack_annotations/ack_annotations.dart';
part 'user.ack.dart';
part 'user.ack.g.dart';
@AckInfer()
final userSchema = Ack.object({
'name': Ack.string().minLength(2),
'email': Ack.string().email(),
});// ✅ AFTER (Ack 2.0)
import 'package:ack/ack.dart';
part 'user.g.dart';
@Schemable()
final userSchema = Ack.object({
'name': Ack.string().minLength(2),
'email': Ack.string().email(),
});
// Generated class User provides:
// - User.schema (AckSchema<Map<String, Object?>, User>)
// - User.parse(...) / User.safeParse(...)
// - User.fromJson(...) / user.toJson() / user.safeToJson()
// - user.copyWith(...) / deep == and hashCode