Serializing JSON Manually in Flutter

Contents

• Core Guidelines
• Workflow: Implementing a Serializable Model
• Workflow: Fetching and Parsing JSON
• Examples

Core Guidelines

• Import

  dart:convert

  : Utilize Flutter's built-in

  dart:convert

  library for manual JSON encoding (

  jsonEncode

  ) and decoding (

  jsonDecode

  ).
• Enforce Type Safety: Always cast the

  dynamic

  result of

  jsonDecode()

  to the expected type, typically

  Map<String, dynamic>

  for objects or

  List<dynamic>

  for arrays.
• Encapsulate Serialization Logic: Define plain model classes containing properties corresponding to the JSON structure. Implement a

  fromJson

  factory constructor and a

  toJson

  method within the model.
• Handle Background Parsing: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's

  compute()

  function to prevent UI jank.
• Throw Exceptions on Failure: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return

  null

  .

Workflow: Implementing a Serializable Model

• Define the plain model class with

  final

  properties.
• Implement the

  factory Model.fromJson(Map<String, dynamic> json)

  constructor.
• Implement the

  Map<String, dynamic> toJson()

  method.
• Write unit tests for both serialization methods.
• Run validator -> review type mismatch errors -> fix casting logic.

1. Define the Model: Create a class with properties matching the JSON keys.
2. Implement

   fromJson

   : Extract values from the

   Map

   and cast them to the appropriate Dart types. Use pattern matching or explicit casting.
3. Implement

   toJson

   : Return a

   Map<String, dynamic>

   mapping the class properties back to their JSON string keys.
4. Validate: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly.

Workflow: Fetching and Parsing JSON

• Execute the HTTP request.
• Validate the response status code.
• Determine parsing strategy (Synchronous vs. Isolate).
• Decode and map the JSON to the model.

1. Execute Request: Use the

   http

   package to perform the network call.
2. Validate Response:
   • If

     response.statusCode == 200

     (or 201 for POST), proceed to parsing.
   • If the status code indicates failure, throw an

     Exception

     .
3. Determine Parsing Strategy:
   • If parsing a small payload (e.g., a single object), parse synchronously on the main thread.
   • If parsing a large payload (e.g., an array of thousands of objects), use

     compute(parseFunction, response.body)

     to parse in a background isolate.
4. Decode and Map: Pass the decoded JSON to your model's

   fromJson

   constructor.

Examples

High-Fidelity Model Implementation

import 'dart:convert';

class User {
  final int id;
  final String name;
  final String email;

  const User({
    required this.id,
    required this.name,
    required this.email,
  });

  // Factory constructor for deserialization
  factory User.fromJson(Map<String, dynamic> json) {
    return switch (json) {
      {
        'id': int id,
        'name': String name,
        'email': String email,
      } => 
        User(
          id: id,
          name: name,
          email: email,
        ),
      _ => throw const FormatException('Failed to load User.'),
    };
  }

  // Method for serialization
  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
    };
  }
}

Synchronous Parsing (Small Payload)

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<User> fetchUser(http.Client client, int userId) async {
  final response = await client.get(
    Uri.parse('https://api.example.com/users/$userId'),
    headers: {'Accept': 'application/json'},
  );

  if (response.statusCode == 200) {
    // Decode returns dynamic, cast to Map<String, dynamic>
    final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
    return User.fromJson(jsonMap);
  } else {
    throw Exception('Failed to load user');
  }
}

Background Parsing (Large Payload)

import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;

// Top-level function required for compute()
List<User> parseUsers(String responseBody) {
  final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
  return parsed.map<User>((json) => User.fromJson(json)).toList();
}

Future<List<User>> fetchUsers(http.Client client) async {
  final response = await client.get(
    Uri.parse('https://api.example.com/users'),
    headers: {'Accept': 'application/json'},
  );

  if (response.statusCode == 200) {
    // Offload expensive parsing to a background isolate
    return compute(parseUsers, response.body);
  } else {
    throw Exception('Failed to load users');
  }
}