Skip to Content
DocsAckGetting StartedWhat’s New & Migration Guide

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’s parse(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: null now encodes its non-null default. A nullable field without a default keeps its existing null behavior.
  • Generated fields follow Dart nullability: T rejects 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>):

PackageRoleKey Capabilities
ackCore 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_generatorTwo-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_dartMCP tool input adapter• server.registerAckTool(name, input: schema, callback: ...), schema.toMcpToolInputSchema(), and parseMcpToolArguments(...); callbacks return CallToolResult and own output validation
ack_firebase_aiFirebase AI (Gemini) adapter• schema.toFirebaseAiResponseJsonSchema() for the map-based GenerationConfig.responseJsonSchema field
ack_json_schema_builderjson_schema_builder bridge• Bidirectional schema.toJsonSchemaBuilder() and jsbSchema.toAckSchema()

2. What Changed & Why

ChangeIntroducedWhat ChangedWhy It Changed
Annotations merged into package:ack1.7.0ack_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() annotation1.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 annotations2.0.0-beta.3Field 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 emitter2.0.0ack_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.0Custom 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> getter1.7.0model.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.0Normalizers 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.0Tri-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 propagation2.0.0SchemaError 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 codegen2.0.0Ack.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 pattern1.7.0Imported 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 ItemRemoved InExact Substitution
ack_annotations package in pubspec.yaml1.7.0Remove ack_annotations; ack includes all annotations.
import 'package:ack_annotations/ack_annotations.dart';1.7.0import 'package:ack/ack.dart';
import 'package:ack_annotations/format_annotations.dart';1.7.0import 'package:ack/ack.dart'; (use the rule annotations)
import 'package:ack/format_annotations.dart';2.0.0import 'package:ack/ack.dart'; (use @IsDateTime(), @IsUri(), @IsIp(), @IsIp(version: 4), @IsIp(version: 6))
json_serializable & json_annotation for @Schemable() models2.0.0Remove unless used by other non-Ack classes; ack_generator emits toJson / fromJson directly.

Model & Field Annotations

Removed SymbolRemoved InExact 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 fields2.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/fields1.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 annotationDeprecated 2.0 beta annotationRule 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 ItemRemoved InExact 2.0 Substitution
part 'model.ack.dart'; + part 'model.ack.g.dart';2.0.0Single part 'model.g.dart';
ack_generator|ack_models & ack_generator|ack_model_json in build.yaml2.0.0ack_generator:ack_generator (plus optional ack_generator:ack_json_schema for .schema.json files)
@AckType() *Type extension type, .args, ModelType.parse(...)2.0.0Generated Model class with typed fields, Model.parse(...), Model.safeParse(...), Model.fromJson(...), model.toJson()
Ack.enumCodec(MyEnum.values)2.0.0Ack.enumValues(MyEnum.values)
schema.toMap()2.0.0schema.toJsonSchema() or schema.toSchemaModel()
server.registerAckModelTool(...) (ack_mcp_dart)2.0.0server.registerAckTool(name, input: Model.schema, callback: ...); return a CallToolResult from the callback
convertAckSchemaModelToBuilder(model) (ack_json_schema_builder)2.0.0schema.toJsonSchemaBuilder()
Ack.fromJsonSchema(...) enforcing format by default2.0.0Pass 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-72.0.0schema.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
Last updated on