---
title: JSON Serialization
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.page/btwld/ack/llms.txt
> Use this file to discover all available pages before exploring further.

Ack validates decoded JSON at your application boundary. On the way back out,
plain schemas produce JSON-native Dart values directly, while
[codecs](./codecs.mdx) 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](./schemas.mdx)'s `safeParse()` method.

```dart
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](./error-handling.mdx).*

## 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:

```dart
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](./typesafe-schemas.mdx) 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.

```dart
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`:

```dart
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:

```dart
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](./codecs.mdx) 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.
