flutter-implement-json-serialization
Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
name: flutter-implement-json-serialization
description: Create model classes with fromJson and toJson methods using dart:convert. Use when manually mapping JSON keys to class properties for simple data structures.
metadata:
model: models/gemini-3.1-pro-preview
last_modified: Tue, 21 Apr 2026 21:44:50 GMT
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-indart:convertlibrary for manual JSON encoding (jsonEncode) and decoding (jsonDecode). - Enforce Type Safety: Always cast the
dynamicresult ofjsonDecode()to the expected type, typicallyMap<String, dynamic>for objects orList<dynamic>for arrays. - Encapsulate Serialization Logic: Define plain model classes containing properties corresponding to the JSON structure. Implement a
fromJsonfactory constructor and atoJsonmethod 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
finalproperties. - 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.
- Define the Model: Create a class with properties matching the JSON keys.
- Implement
fromJson: Extract values from theMapand cast them to the appropriate Dart types. Use pattern matching or explicit casting. - Implement
toJson: Return aMap<String, dynamic>mapping the class properties back to their JSON string keys. - 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.
- Execute Request: Use the
httppackage to perform the network call. - Validate Response:
- If
response.statusCode == 200(or 201 for POST), proceed to parsing. - If the status code indicates failure, throw an
Exception.
- If
- 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.
- Decode and Map: Pass the decoded JSON to your model's
fromJsonconstructor.
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');
}
}
Related
More Data & AI skills
agent-browser
vercel-labs
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sen
grill-with-docs
mattpocock
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
microsoft-foundry
microsoft
Deploy, evaluate, fine-tune, and manage Foundry agents end-to-end with azd: hosted agent scaffold/run/deploy, prompt agent create, batch eval, continuous eval, prompt optimizer, Agent Optimizer scaffold, agent.yaml, dataset curation from traces, model fine-tuning (SFT/DPO/RFT). USE FOR: azd ai agent, azd provision/deploy, deploy agent, hosted agent, create agent, add tool to agent, invoke agent, evaluate agent, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, agent optimizer, deploy model, Foundry project, RBAC, role assignment, permissions, quota, capacity, region, troubleshoot agent, deployment failure, AI Services, create F
azure-ai
microsoft
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-resource-lookup
microsoft
List, find, and show Azure resources across subscriptions or resource groups. Handles prompts like \"list the websites in my subscription\", \"list my web apps\", \"show my app services\", \"list virtual machines\", \"list my VMs\", \"show storage accounts\", \"find container apps\", and \"what resources do I have\". USE FOR: list websites, list web apps, list app services, show websites in subscription, resource inventory, find resources by tag, tag analysis, orphaned resource discovery (not for cost analysis), unattached disks, count resources by type, cross-subscription lookup, and Azure Resource Graph queries. DO NOT USE FOR: deploying/changing resources (use azure-deploy), cost optimiza
azure-aigateway
microsoft
Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway.