JSON models

Why model classes?

jsonDecode gives you maps and lists of dynamic values. Writing post['title'] everywhere is fragile: a typo in a key or a wrong type only fails at run time, maybe on a user's phone. A model class turns JSON into a typed Dart object once, at the edge of your app. After that, the compiler checks every use of order.total, and editors can autocomplete fields.

A hand-written model

{"id": 9081, "item": "Paneer tikka", "qty": 2, "price_paise": 32000, "coupon": null}

class Order {
  const Order({required this.id, required this.item, required this.qty, required this.pricePaise, this.coupon});

  final int id;
  final String item;
  final int qty;
  final int pricePaise;
  final String? coupon;

  factory Order.fromJson(Map<String, dynamic> json) => Order(
        id: json['id'] as int,
        item: json['item'] as String,
        qty: (json['qty'] as int?) ?? 1,             // default if missing
        pricePaise: json['price_paise'] as int,
        coupon: json['coupon'] as String?,           // nullable field
      );

  Map<String, dynamic> toJson() => {
        'id': id,
        'item': item,
        'qty': qty,
        'price_paise': pricePaise,
        'coupon': coupon,
      };

  int get totalPaise => qty * pricePaise;
}

final list = (jsonDecode(response.body) as List<dynamic>)
    .map((e) => Order.fromJson(e as Map<String, dynamic>))
    .toList();

Notice the naming: the API uses price_paise (snake_case) while Dart uses pricePaise (camelCase). The fromJson and toJson methods are the single place where the two styles meet, so the rest of your code never sees the server's naming.

Handling bad data

Servers change, and bugs happen. A field might be missing, null, or a string instead of a number. With as int, a wrong type throws a TypeError at the moment of parsing, which is good: it happens in one predictable place. Catch errors around parsing in your repository and turn them into a clear app error ("Could not read orders"). Use nullable types and defaults only for fields that are truly optional.

Write a small unit test for each fromJson with a real sample response. It catches mistakes cheaply.

Generating code with json_serializable

Writing fromJson and toJson for twenty models is boring and error-prone. json_serializable generates them from annotations. build_runner is the tool that runs code generators.

flutter pub add json_annotation
flutter pub add --dev build_runner json_serializable

import 'package:json_annotation/json_annotation.dart';

part 'order.g.dart';                            // the generated file

@JsonSerializable(fieldRename: FieldRename.snake)
class Order {
  Order({required this.id, required this.item, this.qty = 1, required this.pricePaise, this.coupon});
  final int id;
  final String item;
  final int qty;
  final int pricePaise;
  final String? coupon;

  factory Order.fromJson(Map<String, dynamic> json) => _$OrderFromJson(json);
  Map<String, dynamic> toJson() => _$OrderToJson(this);
}

dart run build_runner build --delete-conflicting-outputs
dart run build_runner watch          # regenerate on every save

Other options exist, such as freezed (immutable classes with copyWith and unions) built on the same generator system. Start with hand-written models to understand them, then use generation when the number of models grows.

Common mistakes

• Using Map<String, dynamic> throughout the UI instead of models.
• Making every field nullable to avoid crashes: then every widget must handle null.
• Forgetting part 'order.g.dart' or not running build_runner: "Undefined name _$OrderFromJson".
• Using double for money from APIs. Prefer integer paise or a decimal type agreed with the backend.