Skip to Content
DocsAckEssentialsJSON Serialization

JSON Serialization

Ack validates decoded JSON at your application boundary. On the way back out, plain schemas produce JSON-native Dart values directly, while codecs encode rich runtime values such as DateTime and Uri back to their wire representation.

Validating JSON data

Validating incoming JSON data involves two steps:

  1. Decode JSON: Use dart:convert to parse the JSON string into a Dart object (usually Map<String, dynamic> or List).
  2. Validate: Pass the decoded object to your Ack schema’s safeParse() method.
import 'dart:convert'; import 'package:ack/ack.dart'; // Define userSchema using correct Ack API final userSchema = Ack.object({ 'name': Ack.string(), 'age': Ack.integer().min(0), 'email': Ack.string().email().nullable(), }); void processApiResponse(String jsonString) { // 1. Decode JSON string into a Dart object. // jsonDecode returns an unknown structure until the schema validates it. Object? jsonData; try { jsonData = jsonDecode(jsonString); } catch (e) { print('Failed to decode JSON: $e'); return; } // 2. Validate the decoded data against your defined schema. final result = userSchema.safeParse(jsonData); if (result.isOk) { // Structure and types are valid. final validDataMap = result.getOrThrow(); print('Valid JSON received: $validDataMap'); // Pass the validated map to your own model layer, // or use an Ack-generated model (see next section). } else { // Handle validation errors (see the Error Handling guide). print('Invalid JSON data: ${result.getError()}'); } } // Example Usage processApiResponse('{"name": "Alice", "age": 30, "email": "alice@example.com"}'); processApiResponse('{"name": "Bob", "age": -5}'); // Invalid: age fails min(0) processApiResponse('{"age": 25}'); // Invalid: missing required field 'name' processApiResponse('not valid json'); // Decoding error

Learn more about Error Handling.

Working with validated data

After successful validation, result.getOrThrow() returns a Map<String, Object?> whose structure and types match your schema. You can work with it directly, pass it into your own model class, or parse it into a generated immutable model:

final result = userSchema.safeParse(jsonData); if (result.isOk) { final validData = result.getOrThrow(); // Option 1: Work directly with the validated Map final name = validData['name'] as String; final age = validData['age'] as int; // Option 2: Pass the validated map into your own model layer // - Constructor: User(name: validData['name'], age: validData['age']) // - generated model: User.parse(validData) // - freezed: User.fromJson(Map<String, dynamic>.from(validData)) // - dart_mappable: UserMapper.fromMap(validData) // - Manual factory: User.fromMap(validData) }

Parsing JSON into generated models

Once a schema is annotated with @Schemable() (see Model Code Generation for setup), parse JSON into a generated immutable model. Public fromJson / toJson cross the source Ack schema and map the validated runtime value directly onto stored fields.

import 'dart:convert'; final jsonData = jsonDecode('{"name": "Alice", "email": "alice@example.com"}'); final result = User.safeParse(jsonData); if (result.isOk) { final user = result.getOrThrow(); print(user.name); // typed String print(user.email); // typed String? }

Encoding validated data

For schemas whose runtime values are already JSON-native (String, num, bool, List, Map, and null), pass the validated value to jsonEncode:

final result = userSchema.safeParse({ 'name': 'Alice', 'age': 30, 'email': 'alice@example.com', }); if (result.isOk) { final validData = result.getOrThrow()!; final jsonString = jsonEncode(validData); print(jsonString); }

When a schema decodes boundary values into richer Dart types, encode through the schema before calling jsonEncode. This applies each codec in the nested structure and restores the JSON-safe boundary shape:

final eventSchema = Ack.object({ 'name': Ack.string(), 'startsAt': Ack.datetime(), }); final event = eventSchema.parse({ 'name': 'Launch', 'startsAt': '2026-01-15T14:00:00Z', }); final boundaryData = eventSchema.encode(event); final jsonString = jsonEncode(boundaryData);

Use safeEncode() when you want a SchemaResult instead of an exception. See Codecs for runtime invariants and custom bidirectional conversions.

Key considerations

  • dart:convert: Use jsonDecode and jsonEncode for JSON text. Ack validates values and encodes codec runtime values back to their boundary representation.
  • Type safety: jsonDecode produces dynamic, but successful validation guarantees the structure and types of the resulting Map<String, Object?>.
  • Model conversion: After validation, how you convert the validated map into an app model is up to you. Generated models parse and encode through an Ack schema and map that runtime value directly onto stored fields in a single .g.dart part. @Schemable() on a top-level schema starts from the schema, while @Schemable() on a class starts from your class.
Last updated on