JSON to Dart: Flutter API Models Fast

Flutter's standard approach to JSON parsing is manual: you write fromJson and toJson methods by hand, mapping each JSON key to a Dart field. For a 10-field API response with two nested objects, that's 60-80 lines of mapping code before you write any real logic. The JSON to Dart converter generates all of it in under a second.

JSON to Dart Type Mapping

In null-safe Dart (2.12+, which covers all current Flutter projects), you must declare nullable fields with ?. If an API sometimes omits a field, String? is correct - String will throw at runtime when the value is missing.

Basic Dart Model

Given a typical API response:

The Dart model is:

Notice (json['score'] as num).toDouble() instead of json['score'] as double. JSON integers and doubles are both num in Dart's type system - if your server occasionally returns 98 instead of 98.0, the direct cast throws. The num cast handles both.

Nested Objects

JSON objects inside objects become separate Dart classes:

The pattern is always the same: cast the nested value to Map, then pass it to the nested class's fromJson. The JSON to Dart converter handles this automatically for any depth of nesting.

Lists and Arrays

The List cast is the correct approach. Don't try to cast directly to List> - that throws at runtime in Dart even when the underlying data is correct, because Dart's generic types are not covariant in this context.

Nullable Fields

Real APIs return nullable fields. Null safety changes how you declare and map them:

json['field'] as String? safely handles both explicit null values and missing keys. For fields that can be absent entirely, you can also use json['field'] as String? ?? 'default' to provide a fallback.

Using json_serializable for Large APIs

For APIs with 10+ models, the manual approach gets tedious. The json_serializable package generates fromJson/toJson from annotations:

Run dart run build_runner build and the user.g.dart file is generated. The @JsonKey(name: 'email_address') annotation handles mismatched key names between your Dart field names and the API JSON keys.

json_serializable is worth the setup overhead once you have more than 5-6 models. For a small number of models, the manual approach is faster and has zero dependencies - pick based on project size, not habit.

Generating Models Quickly

Paste your API response JSON into the JSON to Dart converter and it generates the full model with fromJson, toJson, nested classes, and proper null safety annotations. If you're not sure the API response is valid JSON first, run it through the JSON validator.

For deeply nested responses where you need to understand the structure before writing models, the JSON viewer shows it as an interactive tree - useful when dealing with responses that have 4-5 levels of nesting and you need to figure out which fields you actually need.

One gotcha worth knowing: the converter generates fromJson assuming non-null fields. If your real API returns null for fields marked required, the cast will throw. Check the actual API behavior and add ? to fields that can be null - the type mapping table above is your guide.