Index of every page on this site: llms.txt
All skills
flutter avatar

/flutter-implement-json-serialization

@ff6d472 official
by flutterflutter/agent-plugins3.2k stars
193
Run it yourself

Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.

Use this Skill: https://skilld.dev/gh/flutter/agent-plugins/flutter-implement-json-serialization

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈50 tokens for metadata: the name and description. ≈1.3k when used: this file.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈202 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Serializing JSON Manually in Flutter

Contents

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({
    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');
  }
}

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    This skill provides standard Flutter implementation patterns for manual JSON serialization and network fetching. It follows community best practices, including background parsing for performance and explicit type casting for safety.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: MEDIUM · 1 issue

Signed by skilld at ff6d472. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 7 months ago
Other metadata
metadata
{
  "model": "models/gemini-3.1-pro-preview",
  "last_modified": "Tue, 21 Apr 2026 21:44:50 GMT"
}
  • flutter
  • dart
  • json
  • serialization
  • dart-convert
  • models
  • type-safety
  • http

README badge

README badge for flutter/agent-plugins/flutter-implement-json-serialization

Implements manual JSON serialization for Flutter model classes using `fromJson` and `toJson` methods with `dart:convert`. Guides developers through defining serializable models, validating type safety with pattern matching, and choosing between synchronous or isolate-based parsing for network responses.

Generated from the current SKILL.md.

Does this skill use code generation like `json_serializable`?
No. This skill teaches manual JSON serialization using `dart:convert` and factory constructors. It does not involve code generation or the `json_serializable` package.
When should I use background parsing with `compute()`?
Use `compute()` when parsing large JSON payloads (execution time > 16ms) to avoid UI jank. For single objects or small arrays, parse synchronously on the main thread.
What should I do if the HTTP response status code is not 200?
Throw an `Exception` immediately. Do not return `null` or attempt to parse the response body.
How do I handle type safety when decoding JSON?
Always cast the dynamic result of `jsonDecode()` to the expected type (e.g., `Map<String, dynamic>`), and use pattern matching or explicit casting in your `fromJson` factory constructor to validate field types.

Generated from the current SKILL.md. These answers refresh after source changes.