flutter-implement-json-serialization

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

Use this checklist to implement manual JSON serialization for a data model.

Task Progress:

• 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

Use this conditional workflow when retrieving and parsing JSON from a network request.

Task Progress:

• 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

Synchronous Parsing (Small Payload)

Background Parsing (Large Payload)