When building modern applications with Dart and Flutter, you will frequently work with data from REST APIs, databases, and external services. Most APIs exchange data using JSON (JavaScript Object Notation).

For example, an API might return:

{
  "id": 101,
  "name": "John",
  "email": "john@example.com"
}

Dart needs a way to convert this JSON data into Dart objects and convert Dart objects back into JSON.

This process is called JSON serialization and deserialization.

In this guide, we will learn what JSON serialization means, how Dart handles JSON, how to use jsonEncode() and jsonDecode(), how to create model classes, and how JSON serialization is commonly used in Flutter applications.

---

What Is JSON?

JSON stands for JavaScript Object Notation.

It is a lightweight data format commonly used to exchange information between applications.

A simple JSON object looks like this:

{
  "name": "John",
  "age": 25,
  "isActive": true
}

JSON supports common data structures such as:

• Strings
• Numbers
• Booleans
• Arrays
• Objects
• null

For example:

{
  "name": "John",
  "age": 25,
  "skills": [
    "Dart",
    "Flutter"
  ],
  "address": {
    "city": "Jaipur",
    "country": "India"
  }
}

JSON is widely used because it is easy for both humans and applications to read.

---

What Is JSON Serialization?

Serialization means converting a Dart object or data structure into a JSON-compatible representation.

For example:

Dart Object
     ↓
Serialization
     ↓
JSON

A Dart object:

User(
  id: 1,
  name: 'John',
)

can be converted into:

{
  "id": 1,
  "name": "John"
}

Serialization is commonly needed when sending data to an API.

---

What Is JSON Deserialization?

Deserialization is the opposite process.

It means converting JSON data into a Dart object.

JSON
 ↓
Deserialization
 ↓
Dart Object

For example:

{
  "id": 1,
  "name": "John"
}

can become:

User(
  id: 1,
  name: 'John',
)

Deserialization is commonly used when receiving API responses.

---

Serialization vs Deserialization

The difference is simple:

Process	Direction	Common Use
Serialization	Dart → JSON	Sending data to an API
Deserialization	JSON → Dart	Reading API responses

Think of it like this:

Dart Object
    ↓
Serialization
    ↓
JSON
    ↓
API
    ↓
JSON
    ↓
Deserialization
    ↓
Dart Object

This process is used constantly in Flutter applications that communicate with backend services.

---

Dart’s Built-in JSON Support

Dart provides JSON functionality through the dart:convert library.

Import it like this:

import 'dart:convert';

The two most important functions are:

jsonEncode()

and:

jsonDecode()

---

Using jsonEncode()

jsonEncode() converts a Dart object or data structure into a JSON string.

For example:

import 'dart:convert';

void main() {
  Map<String, dynamic> user = {
    'id': 1,
    'name': 'John',
    'age': 25,
  };

  String jsonData = jsonEncode(user);

  print(jsonData);
}

Output:

{"id":1,"name":"John","age":25}

Here:

Dart Map → JSON String

---

Using jsonDecode()

jsonDecode() converts a JSON string into a Dart object, usually a Map<String, dynamic> or List<dynamic>.

Example:

import 'dart:convert';

void main() {
  String jsonData = '''
  {
    "id": 1,
    "name": "John",
    "age": 25
  }
  ''';

  Map<String, dynamic> user = jsonDecode(jsonData);

  print(user['name']);
  print(user['age']);
}

Output:

John
25

Here:

JSON String → Dart Map

---

JSON Object to Dart Map

Consider this JSON:

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

After decoding:

Map<String, dynamic> user = jsonDecode(jsonData);

you can access values using their keys:

print(user['id']);
print(user['name']);
print(user['email']);

---

JSON Array to Dart List

JSON can also contain arrays.

Example:

[
  {
    "id": 1,
    "name": "John"
  },
  {
    "id": 2,
    "name": "Alex"
  }
]

Decode it:

import 'dart:convert';

void main() {
  String jsonData = '''
  [
    {
      "id": 1,
      "name": "John"
    },
    {
      "id": 2,
      "name": "Alex"
    }
  ]
  ''';

  List<dynamic> users = jsonDecode(jsonData);

  print(users[0]['name']);
  print(users[1]['name']);
}

Output:

John
Alex

The basic structure is:

JSON Array
    ↓
List<dynamic>

---

Why Use Dart Model Classes?

Although you can work directly with Map<String, dynamic>, model classes are generally better for larger applications.

Instead of:

print(user['name']);
print(user['email']);

you can create:

User user = User.fromJson(jsonData);

print(user.name);
print(user.email);

Model classes provide:

• Better type safety
• Cleaner code
• Easier maintenance
• Better autocomplete
• Easier validation
• Reusable data structures
• Cleaner API integration

This is why model classes are commonly used in professional Flutter applications.

---

Creating a Dart Model

Suppose an API returns:

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

Create a Dart model:

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

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

Now you have a strongly typed representation of the JSON data.

---

Creating a fromJson() Method

The next step is converting JSON data into a User object.

Add a factory constructor:

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

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }
}

Now you can deserialize JSON:

import 'dart:convert';

void main() {
  String jsonData = '''
  {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  }
  ''';

  Map<String, dynamic> json = jsonDecode(jsonData);

  User user = User.fromJson(json);

  print(user.name);
  print(user.email);
}

Output:

John
john@example.com

---

Creating a toJson() Method

Now suppose you want to convert the Dart object back into JSON.

Add a toJson() method:

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

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }

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

Now:

User user = User(
  id: 1,
  name: 'John',
  email: 'john@example.com',
);

Map<String, dynamic> json = user.toJson();

print(json);

You can also convert it into a JSON string:

String jsonString = jsonEncode(user.toJson());

print(jsonString);

---

Complete Serialization and Deserialization Example

Here is a complete example:

import 'dart:convert';

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

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }

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

void main() {
  // JSON response
  String jsonString = '''
  {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  }
  ''';

  // Deserialize JSON
  Map<String, dynamic> jsonData = jsonDecode(jsonString);

  User user = User.fromJson(jsonData);

  print(user.name);

  // Serialize Dart object
  Map<String, dynamic> userJson = user.toJson();

  String output = jsonEncode(userJson);

  print(output);
}

This example demonstrates both directions:

JSON String
    ↓
jsonDecode()
    ↓
Map
    ↓
User.fromJson()
    ↓
User Object
    ↓
toJson()
    ↓
Map
    ↓
jsonEncode()
    ↓
JSON String

---

Handling Nullable JSON Fields

API responses often contain fields that may be null.

For example:

{
  "id": 1,
  "name": "John",
  "phone": null
}

Your Dart model should reflect that possibility:

class User {
  final int id;
  final String name;
  final String? phone;

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      phone: json['phone'],
    );
  }
}

Now phone can contain either a string or null.

---

Providing Default Values

Sometimes an API field may be missing or null.

You can provide a default value:

factory User.fromJson(Map<String, dynamic> json) {
  return User(
    id: json['id'] ?? 0,
    name: json['name'] ?? '',
    email: json['email'] ?? '',
  );
}

For example:

json['name'] ?? ''

means:

Use the JSON name if it exists; otherwise use an empty string.

Use defaults carefully. A missing required API field may indicate malformed data, and silently replacing it can hide backend problems.

---

Nested JSON Objects

Real-world APIs often contain nested objects.

For example:

{
  "id": 1,
  "name": "John",
  "address": {
    "city": "Jaipur",
    "country": "India"
  }
}

Create an Address model:

class Address {
  final String city;
  final String country;

  Address({
    required this.city,
    required this.country,
  });

  factory Address.fromJson(Map<String, dynamic> json) {
    return Address(
      city: json['city'],
      country: json['country'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'city': city,
      'country': country,
    };
  }
}

Then use it inside User:

class User {
  final int id;
  final String name;
  final Address address;

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      address: Address.fromJson(json['address']),
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'address': address.toJson(),
    };
  }
}

This approach keeps nested JSON models clean and reusable.

---

JSON Arrays Inside Objects

Consider an API response like:

{
  "id": 1,
  "name": "John",
  "skills": [
    "Dart",
    "Flutter",
    "Firebase"
  ]
}

The model can use:

class User {
  final int id;
  final String name;
  final List<String> skills;

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      skills: List<String>.from(json['skills']),
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'skills': skills,
    };
  }
}

This converts the JSON array into a strongly typed Dart list.

---

JSON Arrays of Objects

A very common API response is an array of objects:

[
  {
    "id": 1,
    "name": "John"
  },
  {
    "id": 2,
    "name": "Alex"
  }
]

Decode the response:

List<dynamic> jsonList = jsonDecode(jsonString);

Convert each item into a User:

List<User> users = jsonList
    .map((json) => User.fromJson(json))
    .toList();

Now you have:

List<User>

instead of:

List<dynamic>

This is much easier to work with in Flutter.

---

A Complete List Deserialization Example

import 'dart:convert';

class User {
  final int id;
  final String name;

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
    );
  }
}

void main() {
  String jsonString = '''
  [
    {
      "id": 1,
      "name": "John"
    },
    {
      "id": 2,
      "name": "Alex"
    },
    {
      "id": 3,
      "name": "David"
    }
  ]
  ''';

  List<dynamic> jsonList = jsonDecode(jsonString);

  List<User> users = jsonList
      .map((json) => User.fromJson(json))
      .toList();

  for (User user in users) {
    print('${user.id}: ${user.name}');
  }
}

Output:

1: John
2: Alex
3: David

---

Working With Dates in JSON

Dates are often returned from APIs as strings.

For example:

{
  "name": "John",
  "createdAt": "2026-08-21T10:30:00Z"
}

The JSON value is a string, but your Dart model may want a DateTime.

class User {
  final String name;
  final DateTime createdAt;

  User({
    required this.name,
    required this.createdAt,
  });

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      name: json['name'],
      createdAt: DateTime.parse(json['createdAt']),
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'name': name,
      'createdAt': createdAt.toIso8601String(),
    };
  }
}

This converts:

JSON String
     ↓
DateTime

and when serializing:

DateTime
     ↓
ISO String

---

Working With API Responses

JSON serialization becomes especially useful when consuming APIs.

A typical Flutter API workflow looks like:

Flutter App
    ↓
HTTP Request
    ↓
Backend API
    ↓
JSON Response
    ↓
jsonDecode()
    ↓
Dart Model
    ↓
UI

For example, after receiving an HTTP response:

final data = jsonDecode(response.body);

You can convert the result into a model:

User user = User.fromJson(data);

Now your UI can work with:

user.name
user.email
user.id

instead of repeatedly accessing JSON keys.

---

Why Model Classes Are Better Than Raw Maps

You can technically write:

print(jsonData['name']);

But as your application grows, this becomes difficult to maintain.

Compare:

print(user['name']);
print(user['email']);
print(user['address']['city']);

with:

print(user.name);
print(user.email);
print(user.address.city);

The model-based approach is generally:

• Easier to read
• More type-safe
• Easier to refactor
• Better supported by IDE autocomplete
• Easier to test
• Easier to reuse

---

Code Generation for JSON Serialization

For larger Flutter applications, manually writing fromJson() and toJson() for every model can become repetitive.

Dart and Flutter projects can use code-generation tools to generate serialization code from annotated model classes.

One commonly used approach is the json_serializable ecosystem.

A typical model looks like:

import 'package:json_annotation/json_annotation.dart';

part 'user.g.dart';

@JsonSerializable()
class User {
  final int id;
  final String name;
  final String email;

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

  factory User.fromJson(Map<String, dynamic> json) =>
      _$UserFromJson(json);

  Map<String, dynamic> toJson() =>
      _$UserToJson(this);
}

The generated file contains the repetitive serialization logic.

This approach is particularly useful when your project has many models.

---

Manual vs Generated Serialization

Both approaches have their place.

Approach	Best For
Manual fromJson() / toJson()	Small projects and learning
Code generation	Medium and large applications
Raw Map<String, dynamic>	Simple or temporary data handling

Manual Serialization

Advantages:

• Easy to understand
• No code-generation setup
• Good for beginners
• Full control

Disadvantages:

• Repetitive
• Easy to make mistakes
• More maintenance for large projects

Code Generation

Advantages:

• Less boilerplate
• Consistent generated code
• Useful for many models
• Easier to maintain large model layers

Disadvantages:

• Requires additional setup
• Generated files must be kept in sync
• Adds build/code-generation steps

---

Common JSON Serialization Mistakes

Mistake 1: Assuming Every Field Exists

This can cause problems:

name: json['name'],

if the API sometimes omits name.

Understand your backend contract and decide whether the field should be required, nullable, or given a safe default.

---

Mistake 2: Incorrect Data Types

Suppose the API returns:

{
  "age": 25
}

Your model should use an appropriate numeric type:

final int age;

Don’t assume that every number is a string.

---

Mistake 3: Forgetting Nested Models

Avoid keeping deeply nested JSON as raw maps throughout your application.

Instead of:

json['address']['city']

create an Address model:

user.address.city

---

Mistake 4: Ignoring Null Safety

If the backend can return:

{
  "phone": null
}

your model should account for that:

final String? phone;

---

Mistake 5: Not Handling Invalid JSON

JSON parsing can fail.

For example:

try {
  final data = jsonDecode(response.body);
} catch (error) {
  print('Invalid JSON: $error');
}

In a production application, error handling should be designed according to the API layer and application architecture rather than simply printing the exception.

---

Best Practices for Dart JSON Serialization

Follow these practices when working with JSON in Dart:

Use Model Classes

Create models for important API entities.

Use Strong Types

Prefer:

final String name;

over unnecessary dynamic values.

Handle Nullable Fields

Use ? for fields that can genuinely be absent or null.

Keep JSON Logic Inside Models

Use:

User.fromJson()

and:

user.toJson()

rather than spreading JSON parsing throughout your UI.

Validate API Assumptions

Make sure your Dart model matches the actual backend response.

Use Code Generation for Large Projects

If you have many models, generated serialization code can significantly reduce repetitive work.

---

Practical Flutter JSON Architecture

A clean Flutter application can separate responsibilities like this:

lib/
├── models/
│   └── user_model.dart
│
├── services/
│   └── api_service.dart
│
├── repositories/
│   └── user_repository.dart
│
├── controllers/
│   └── user_controller.dart
│
└── screens/
    └── user_screen.dart

The flow can be:

API
 ↓
API Service
 ↓
JSON
 ↓
User.fromJson()
 ↓
User Model
 ↓
Repository / Controller
 ↓
UI

This keeps JSON parsing separate from the user interface and makes the application easier to maintain.

---

Complete Real-World Example

Here is a simplified example of receiving a JSON response and converting it into Dart models:

import 'dart:convert';

class Address {
  final String city;
  final String country;

  Address({
    required this.city,
    required this.country,
  });

  factory Address.fromJson(Map<String, dynamic> json) {
    return Address(
      city: json['city'],
      country: json['country'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'city': city,
      'country': country,
    };
  }
}

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

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
      address: Address.fromJson(json['address']),
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
      'address': address.toJson(),
    };
  }
}

void main() {
  const jsonString = '''
  {
    "id": 1,
    "name": "John",
    "email": "john@example.com",
    "address": {
      "city": "Jaipur",
      "country": "India"
    }
  }
  ''';

  final Map<String, dynamic> jsonData =
      jsonDecode(jsonString);

  final User user = User.fromJson(jsonData);

  print(user.name);
  print(user.email);
  print(user.address.city);

  final Map<String, dynamic> output =
      user.toJson();

  print(jsonEncode(output));
}

This example demonstrates the complete JSON flow:

JSON
 ↓
jsonDecode()
 ↓
Map<String, dynamic>
 ↓
User.fromJson()
 ↓
User Object
 ↓
toJson()
 ↓
Map<String, dynamic>
 ↓
jsonEncode()
 ↓
JSON

---

Dart JSON Serialization Roadmap

If you are learning this topic from scratch, follow this order:

1. Understand JSON
       ↓
2. Learn dart:convert
       ↓
3. Learn jsonDecode()
       ↓
4. Learn jsonEncode()
       ↓
5. Work with Map<String, dynamic>
       ↓
6. Create Dart model classes
       ↓
7. Learn fromJson()
       ↓
8. Learn toJson()
       ↓
9. Handle nested objects
       ↓
10. Handle JSON lists
       ↓
11. Handle nullable fields
       ↓
12. Handle DateTime
       ↓
13. Connect models to APIs
       ↓
14. Learn code generation

---

Conclusion

JSON serialization and deserialization are essential skills for Dart and Flutter developers because most modern applications communicate with backend services using JSON.

The two basic operations are:

jsonDecode()

for converting JSON into Dart data, and:

jsonEncode()

for converting Dart data into JSON.

For simple applications, you can work directly with Map<String, dynamic>. For larger applications, creating strongly typed model classes with fromJson() and toJson() methods provides cleaner and more maintainable code.

As you progress toward professional Flutter development, you should also learn nested JSON models, JSON lists, nullable fields, date conversion, API integration, and code-generation approaches.

Once you understand JSON serialization properly, working with REST APIs and backend services in Flutter becomes much easier.

Frequently Asked Questions

What is JSON serialization in Dart?

JSON serialization is the process of converting Dart data into a JSON-compatible format, usually before sending it to an API.

What is JSON deserialization?

Deserialization is the process of converting JSON data received from an API into Dart data or model objects.

Which library does Dart use for JSON?

Dart provides JSON functionality through the built-in dart:convert library.

What does jsonDecode() do?

jsonDecode() converts a JSON string into a Dart value such as a Map or List.

What does jsonEncode() do?

jsonEncode() converts Dart data structures into a JSON string.

Why should I use fromJson()?

fromJson() provides a convenient and reusable way to convert JSON data into a strongly typed Dart model object.

Why should I use toJson()?

toJson() converts a Dart model object into a Map<String, dynamic> that can then be encoded as JSON and sent to an API.

Should I manually write JSON serialization code?

For small projects and learning, manual fromJson() and toJson() methods are perfectly reasonable. For larger projects with many models, code generation can reduce repetitive serialization code.

Related Topics: Dart Programming, Dart JSON, JSON Serialization, JSON Deserialization, Dart Models, Flutter API Integration, REST API Flutter, Dart jsonEncode, Dart jsonDecode, Flutter Development, Dart Tutorial