Ack 1.1.0

Ack 1.1.0

Ack 1.1.0 is a correctness-focused release that aligns runtime validation,
generated schemas, and tooling with their documented contracts. It does not
change the public Dart API surface.

Validation and schema fixes

• Keep safeParse non-throwing for recoverable callback exceptions while
  preserving Dart Error values so programming defects remain visible.
• Bound direct, indirect, and wrapper-mediated lazy-schema recursion.
• Decode RFC 3339 date-times that use lowercase t and z separators.
• Validate multipleOf, IPv6, RFC 3339 date-times, range bounds, collection
  limits, unions, and enum definitions consistently with JSON Schema.
• Snapshot factory collections and correct schema/deep-collection equality.
• Preserve conflicting JSON Schema keywords through allOf, and export exact
  list/object sizes with the correct Draft-7 keywords.

Generator and tooling

• Reject nullable list element schemas during generation, matching Ack's
  runtime list contract.
• Use current source_gen diagnostics without undeclared debug-file output.
• Add stable full-output generator coverage.
• Make API checks, changelog updates, workspace setup, and root test orchestration
  fail truthfully instead of producing false-green results.

Behavior changes and migration notes

Although the public API is unchanged, invalid or ambiguous inputs that were
previously accepted may now fail earlier:

• Fix invalid schema definitions reported by construction-time ArgumentErrors.
• Put list nullability on the list (Ack.list(item).nullable()), not its item.
• Treat accumulated floating-point sums deliberately: round first or validate
  integer minor units such as cents before applying multipleOf.
• Refresh snapshots that assert the exact output of toJsonSchema().
• Expect AckException from parse() when a recoverable constraint or
  refinement callback throws; inspect the underlying cause for diagnostics.

See the package changelogs for the complete behavior notes.

Release v1.0.1

Release v1.0.1

This patch hardens recursive schemas built with Ack.lazy against unbounded recursion.

Bug Fixes

• Recursion depth guard for Ack.lazy / LazySchema (#122): recursive schemas now
  enforce a maximum recursion depth (default 100) on parse, runtime validation, and
  encode. Previously, cyclic or arbitrarily deep input could recurse without bound and
  risk a stack overflow. Exceeding the limit now fails fast with a descriptive validation
  error (lazy_max_depth: "Maximum recursion depth (N) exceeded.") instead of crashing.

Improvements

• Ack.lazy(...) accepts an optional maxDepth (default LazySchema.defaultMaxDepth
  = 100; must be >= 1), carried through copyWith, equality, and serialization.
• JSON Schema export warns that the runtime-only maxDepth check can't be expressed via
  $ref and is omitted from the exported schema.

Behavior note: recursion is now capped at depth 100 by default. Structures that
legitimately nest deeper must pass an explicit higher maxDepth.

The other packages (ack_annotations, ack_generator, ack_json_schema_builder,
ack_firebase_ai) are version-aligned to 1.0.1 with no functional changes.

v1.0.0

Ack 1.0.0

Ack 1.0.0 is the first stable release of Ack, a schema validation library for Dart and Flutter. Ack helps you validate untrusted data at application boundaries, reuse the same schemas across runtime validation and JSON workflows, and generate typed wrappers when you want stronger ergonomics than map access.

Start with the documentation site or jump straight into the Quickstart Tutorial.

What is included

• Fluent schema definitions for strings, numbers, booleans, objects, lists, enums, literals, unions, discriminated unions, and recursive schemas.
• Validation rules for common constraints such as string length, patterns, email, UUID, URI, numeric ranges, list length, uniqueness, and custom checks.
• Clear error handling through safeParse, SchemaResult, structured paths, and readable validation messages.
• JSON serialization workflows for validating decoded API responses and working with validated data safely.
• Codecs for bidirectional conversion between wire values and Dart runtime values, including dates, datetimes, URIs, durations, enums, and custom conversions.
• Type-safe schema generation with @AckType() for extension types, typed getters, parse, and safeParse.
• JSON Schema export through toJsonSchema() and the reusable schema-model boundary for adapter authors.
• Flutter form validation examples for using Ack schemas in form fields.
• Common recipes for API responses, reusable schemas, composition, enums, and other everyday validation tasks.
• API reference covering the stable surface in one place.

Packages

• ack: core runtime validation library.
• ack_annotations: @AckType() annotation package.
• ack_generator: build_runner generator for typed schema wrappers.
• ack_json_schema_builder: adapter for json_schema_builder.
• ack_firebase_ai: Firebase AI structured-output schema adapter.

For AI agents

Ack also publishes an llms.txt index with a compact overview of the packages, core APIs, code generation workflow, and common examples.

Release quality

This release was validated with the full package test suites, documentation checks, example tests, and pub.dev dry-runs before publishing. All five packages are now available on pub.dev at version 1.0.0.

v1.0.0-beta.12

ack 1.0.0-beta.12

ack

Breaking

• DoubleSchema and NumberSchema now reject non-finite values (NaN, Infinity, -Infinity) during runtime validation by default, aligning numeric schemas with JSON-safe values.
• Removed the retired JSON Schema DTO converter APIs.
• Replaced the interim JSON Schema model-kind API with sealed AckSchemaModel variants and a canonical AckSchema.toSchemaModel() adapter conversion.

Added

• Ack.enumCodec<T extends Enum>(List<T> values) returns a CodecSchema<String, T> wrapping EnumSchema<T>.
• NumberSchemaExtensions adds fluent numeric constraints to Ack.number(): .min, .max, .greaterThan, .lessThan, .positive, .negative, .multipleOf.

Changed

• Discriminated schemas are projected through union-owned discriminator branches.
• Defaults, const values, extension keywords, transformed metadata, composition, and JSON Schema constraints are preserved through the schema-model boundary.

Migration

• Re-run tests for code paths that parse or encode double/num values. If a boundary must accept NaN/infinities, model that value outside the JSON numeric schema path before validation.

ack_annotations

Breaking — Removed AckModel, AckField, and decorator annotations. Only @AckType() remains.

ack_generator

Breaking — Removed class-based schema generation. Only top-level @AckType() schema variables and getters are supported.

ack_firebase_ai

• Added toFirebaseAiResponseJsonSchema() for Firebase AI's GenerationConfig.responseJsonSchema path, plus committed golden fixtures and native fixture corpora.
• Removed typed Firebase AI Schema conversion APIs — use toFirebaseAiResponseJsonSchema() instead.

ack_json_schema_builder

• Routes conversion through ACK's sealed AckSchemaModel boundary and generic Draft-7 JSON Schema renderer; preserves defaults, const values, extension keywords, transformed metadata, and composition.
• Removed the retired JSON Schema DTO converter path.

---

All five packages are released in lockstep at 1.0.0-beta.12.

Release v1.0.0-beta.7

Release v1.0.0-beta.7

This release adds top-level enum/literal schema constructors, deprecates chained string schema methods, and improves the code generator's nested schema resolution.

Key Features

• Top-level enum and literal schemas: New Ack.enumString(), Ack.literal(), and Ack.enumValues() constructors for creating enum and literal schemas directly (#73)
• Schema result mapping: New SchemaResult.map() for transforming validated values
• Cross-file schema resolution: Generator now resolves nested schemas across files with strict typing (#77)

Deprecations

• StringSchema.literal() and StringSchema.enumString() are deprecated — use Ack.literal() and Ack.enumString() instead (#74)

Improvements

• Refactored AckType conversion helpers for cleaner generated code (#72)
• Major improvements to schema AST analyzer for correctness in complex nested scenarios

Packages

Package	Version
ack	1.0.0-beta.7
ack_annotations	1.0.0-beta.7
ack_generator	1.0.0-beta.7
ack_firebase_ai	1.0.0-beta.7
ack_json_schema_builder	1.0.0-beta.7

v1.0.0-beta.6

What's Changed

• refactor: simplify validation workflow by eliminating duplicate nullable handling by @leoafarias in #17
• Release 1.0.0-beta.1 by @leoafarias in #19
• feat: add custom name parameter to @AckType annotation by @leoafarias in #22
• docs: improve passthrough and additional properties documentation by @leoafarias in #23
• feat: add args getter for extension types with additionalProperties by @leoafarias in #24
• chore: exclude example package from versioning and releases by @leoafarias in #25
• docs: enhance documentation with detailed examples and error handling by @leoafarias in #20
• feat: add date/datetime validation with min/max constraints by @leoafarias in #26
• refactor: modernize constraint switch statements to expressions by @leoafarias in #27
• refactor: flatten constraints folder structure and add type prefixes by @leoafarias in #28
• fix: critical error handling, documentation, and immutability improvements for 1.0.0 by @leoafarias in #29
• feat: enhance setup script with robust environment configuration by @leoafarias in #31
• feat: Firebase AI schema converter package and ACK improvements by @leoafarias in #32
• chore: Add schema converter package development guides by @leoafarias in #33
• Update ci.yml by @tilucasoli in #35
• fix: preserve nullable metadata in firebase ai converter by @leoafarias in #36
• chore: Update melos.yaml by @tilucasoli in #38
• feat: add ack_json_schema_builder converter package by @leoafarias in #37
• refactor: consolidate JSON schema utilities and reduce duplication by @leoafarias in #40
• fix(ack_json_schema_builder): complete JSON schema conversion coverage by @leoafarias in #45
• refactor: Update for analyzer >=7.x <9 API changes by @tilucasoli in #41
• fix: Add field descriptions to generated schema output by @tilucasoli in #44
• refactor: deprecate withDescription in favor of describe by @leoafarias in #46
• fix(generator): support Ack.list(schemaRef) for typed list getters by @leoafarias in #47
• refactor: apply DRY improvements to schema classes by @leoafarias in #53
• Update release workflow and ack package versions to 1.0.0-beta.4 by @tilucasoli in #54
• chore: Migrate to Dart 3.8 workspace and update Melos config by @tilucasoli in #55
• chore: Update meta and test dependencies in pubspecs by @tilucasoli in #56
• docs: Fix broken links and add missing API documentation by @leoafarias in #57
• docs: Add llms.txt for AI agent documentation by @leoafarias in #58
• Fix @AckType schema ref casts and tests by @leoafarias in #59
• fix(generator): resolve list element types with method chain modifiers by @leoafarias in #60
• feat(generator): support doc comments for schema descriptions by @leoafarias in #61
• feat(schemas): implement value-based equality for schemas and constraints by @leoafarias in #63
• Release: v1.0.0-beta.5 for all ack packages by @tilucasoli in #64
• feat(schemas): enforce Map-returning child schemas in discriminated unions by @leoafarias in #67
• refactor(schemas): centralize null/default handling and extract ObjectSchema helpers by @leoafarias in #65
• fix(generator): comprehensive fixes for primitives and correctness by @leoafarias in #50
• chore(release): finalize v1.0.0-beta.6 release metadata and workflow by @leoafarias in #69

New Contributors

• @tilucasoli made their first contribution in #35

Full Changelog: 0.3.0-beta.1...v1.0.0-beta.6

v1.0.0-beta.5

What's Changed

• refactor: simplify validation workflow by eliminating duplicate nullable handling by @leoafarias in #17
• Release 1.0.0-beta.1 by @leoafarias in #19
• feat: add custom name parameter to @AckType annotation by @leoafarias in #22
• docs: improve passthrough and additional properties documentation by @leoafarias in #23
• feat: add args getter for extension types with additionalProperties by @leoafarias in #24
• chore: exclude example package from versioning and releases by @leoafarias in #25
• docs: enhance documentation with detailed examples and error handling by @leoafarias in #20
• feat: add date/datetime validation with min/max constraints by @leoafarias in #26
• refactor: modernize constraint switch statements to expressions by @leoafarias in #27
• refactor: flatten constraints folder structure and add type prefixes by @leoafarias in #28
• fix: critical error handling, documentation, and immutability improvements for 1.0.0 by @leoafarias in #29
• feat: enhance setup script with robust environment configuration by @leoafarias in #31
• feat: Firebase AI schema converter package and ACK improvements by @leoafarias in #32
• chore: Add schema converter package development guides by @leoafarias in #33
• Update ci.yml by @tilucasoli in #35
• fix: preserve nullable metadata in firebase ai converter by @leoafarias in #36
• chore: Update melos.yaml by @tilucasoli in #38
• feat: add ack_json_schema_builder converter package by @leoafarias in #37
• refactor: consolidate JSON schema utilities and reduce duplication by @leoafarias in #40
• fix(ack_json_schema_builder): complete JSON schema conversion coverage by @leoafarias in #45
• refactor: Update for analyzer >=7.x <9 API changes by @tilucasoli in #41
• fix: Add field descriptions to generated schema output by @tilucasoli in #44
• refactor: deprecate withDescription in favor of describe by @leoafarias in #46
• fix(generator): support Ack.list(schemaRef) for typed list getters by @leoafarias in #47
• refactor: apply DRY improvements to schema classes by @leoafarias in #53
• Update release workflow and ack package versions to 1.0.0-beta.4 by @tilucasoli in #54
• chore: Migrate to Dart 3.8 workspace and update Melos config by @tilucasoli in #55
• chore: Update meta and test dependencies in pubspecs by @tilucasoli in #56
• docs: Fix broken links and add missing API documentation by @leoafarias in #57
• docs: Add llms.txt for AI agent documentation by @leoafarias in #58
• Fix @AckType schema ref casts and tests by @leoafarias in #59
• fix(generator): resolve list element types with method chain modifiers by @leoafarias in #60
• feat(generator): support doc comments for schema descriptions by @leoafarias in #61
• feat(schemas): implement value-based equality for schemas and constraints by @leoafarias in #63

Full Changelog: 0.3.0-beta.1...v1.0.0-beta.5

v0.3.0-beta.1

What's Changed

✨ New Features

• Discriminated Union Schemas: New schema type for polymorphic validation based on discriminator fields
• Dart Mappable Integration: Seamless field name synchronization for model generation
• Unified API Compatibility Checking: Single melos api-check command replaces 19 complex shell commands

🔄 API Modernization & Deprecations

Multiple constraint classes have been deprecated in favor of unified ComparisonConstraint and PatternConstraint implementations:

String Constraints (use PatternConstraint instead):

• StringDateTimeConstraint → PatternConstraint.dateTime()
• StringDateConstraint → PatternConstraint.date()
• StringEnumConstraint → PatternConstraint.enumValues()
• StringEmailConstraint → PatternConstraint.email()
• StringRegexConstraint → PatternConstraint.regex()
• StringJsonValidator → PatternConstraint.json()

Numeric Constraints (use ComparisonConstraint instead):

• NumberMinConstraint → ComparisonConstraint.numberMin()
• NumberMaxConstraint → ComparisonConstraint.numberMax()
• NumberRangeConstraint → ComparisonConstraint.numberRange()
• NumberExclusiveMinConstraint → ComparisonConstraint.numberExclusiveMin()
• NumberExclusiveMaxConstraint → ComparisonConstraint.numberExclusiveMax()
• NumberMultipleOfConstraint → ComparisonConstraint.numberMultipleOf()

Collection Constraints (use ComparisonConstraint instead):

• StringMinLengthConstraint → ComparisonConstraint.stringMinLength()
• StringMaxLengthConstraint → ComparisonConstraint.stringMaxLength()
• ListMinItemsConstraint → ComparisonConstraint.listMinItems()
• ListMaxItemsConstraint → ComparisonConstraint.listMaxItems()
• ObjectMinPropertiesConstraint → ComparisonConstraint.objectMinProperties()
• ObjectMaxPropertiesConstraint → ComparisonConstraint.objectMaxProperties()

🛠️ Schema API Changes

• SchemaRegistry: Simplified type signatures - removed model type parameter
• SchemaModel: Method signature updates for parse() and tryParse()
• Extension Methods: Deprecated legacy method names on schema extensions

📚 Documentation & Tooling

• Consolidated API documentation and tooling
• Enhanced constraint migration guidance
• Simplified development workflow with unified commands

All deprecated APIs remain functional with migration guidance. See the deprecations for detailed migration paths.

Full Changelog: v0.2.0-beta.1...0.3.0-beta.1

v0.2.0-beta.1

Release v0.2.0-beta.1

This release introduces significant improvements to the SchemaModel API, enhanced string validation, and better OpenAPI integration.

Key Features

• Code Generation: Generate schema classes from your models
• Type-safe Schema Access: Direct property getters with proper types
• Automatic Validation: Validation happens during construction
• Multiple Validation Approaches: Choose what fits your workflow
• Improved String Validation: New pattern matching options
• JSON Schema Integration: Generate API specifications automatically

Code Generation

Define Your Models

Annotate your models with validation rules:

@Schema()
class Product {
  @IsNotEmpty()
  final String id;

  @MinLength(3)
  final String name;

  final double price;

  final Category category;

  Product({
    required this.id,
    required this.name,
    required this.price,
    required this.category,
  });
}

Run the Generator

Use the build_runner to generate schema classes:

dart run build_runner build --delete-conflicting-outputs

This creates a .schema.dart file with your generated schemas.

SchemaModel API

Creating Schemas

The constructor now validates data automatically:

// Create schema with automatic validation
final schema = ProductSchema({
  'id': '123',
  'name': 'Test Product',
  'price': 19.99
});

// Check if valid
bool valid = schema.isValid;

Accessing Schema Values

Access validated data with type-safe getters:

// Type-safe access to properties
String id = schema.id;
String name = schema.name;
double price = schema.price;

// Access nested schema objects
CategorySchema category = schema.category;
String categoryName = category.name;

Handling Validation Errors

Get detailed error information when validation fails:

if (!schema.isValid) {
  SchemaError? error = schema.getErrors();
  
  // Error details
  String errorType = error?.name;       // e.g., "required_field"
  String message = error?.message;      // e.g., "Required field is missing"
  String? path = error?.path;           // e.g., "category.id"
}

Converting to Models

Transform schema data to strongly-typed models:

// Convert schema to model instance
Product product = schema.toModel();

// Access model properties
String id = product.id;
Category category = product.category;

Alternative Validation Approaches

Choose your preferred validation style:

// Approach 1: Constructor + isValid check
final schema = ProductSchema(data);
if (schema.isValid) {
  final product = schema.toModel();
}

// Approach 2: Direct parse (throws on failure)
try {
  Product product = ProductSchema.parse(data);
} catch (e) {
  // Handle validation error
}

// Approach 3: Try-parse (returns null on failure)
Product? product = ProductSchema.tryParse(data);
if (product != null) {
  // Use valid product
}

Creating Schema from Model

Convert model instances to schemas for serialization:

// Create schema from model instance
final schema = ProductSchema.fromModel(product);

// Serialize to various formats
Map<String, Object?> map = schema.toMap();
String json = schema.toJson();

Enhanced String Validation

Full Pattern Matching

The matches() method now validates entire strings:

// Full string pattern matching (with anchors)
final schema = Ack.string.matches('^[a-z0-9_]{3,16}$');
schema.validate('user_123').isOk;  // true
schema.validate('user@123').isOk;  // false - contains @

Partial String Matching

New contains() method for substring matching:

// Partial string matching
final schema = Ack.string.contains('important');
schema.validate('This is important text').isOk;  // true
schema.validate('Nothing here').isOk;  // false

JSON Schema Integration

Generate API specifications from your schemas:

// Get JSON Schema
Map<String, Object?> jsonSchema = ProductSchema.toJsonSchema();

// Convert to JSON string
String jsonString = jsonEncode(jsonSchema);

Migration Guide

If you're upgrading from 0.1.x, note these changes:

1. Update string pattern validation:

   // Old (0.1.x): Matches substrings
   Ack.string.matches('abc');  // Would match 'abcdef'
   
   // New (0.2.0): Matches whole string
   Ack.string.matches('^abc$'); // Only matches 'abc' exactly
   Ack.string.contains('abc');  // Matches substrings, like old matches()

2. Use the new validation workflow:

   // Create and validate in one step
   final schema = ProductSchema(data);
   
   // Check isValid before using
   if (schema.isValid) {
     schema.id;              // Access schema properties
     schema.category.name;   // Access nested properties
     
     // Or convert to model
     final product = schema.toModel();
   }

Documentation

Full documentation is available at https://docs.page/btwld/ack

0.1.1

Full Changelog: 0.1.0...0.1.1