In Dart, what does jsonDecode return, and why does decoded JSON need casts or patterns before you can use it as typed data?
answer
- the return type is dynamic
- objects become Map<String, dynamic>
- arrays become List<dynamic>
- as List<String> fails, cast<String>() works
- whole numbers decode as int
basics
~10 sjsonDecode returns dynamic: objects become Map<String, dynamic>, arrays List<dynamic>, numbers int or double. Nothing is checked against your types, so you cast, convert lists with cast() or List.from, or validate with a pattern.
solid answer
~40 s`jsonDecode(source)` returns `dynamic`, and the value inside is built only from `Map<String, dynamic>`, `List<dynamic>`, `String`, `num`, `bool` and `null`. Dart cannot know your schema, so the compiler lets `dynamic` flow anywhere and failures appear at runtime. Three traps: `as List<String>` throws, because the runtime object is a `List<dynamic>` whatever it contains, so use `.cast<String>()` or `List<String>.from(...)`; a whole number such as `1` decodes as `int`, so `as double` fails and `(x as num).toDouble()` is safer; and a missing key yields `null`. I validate the shape with a Dart 3 pattern such as `if (data case {'theme': String theme})`, or in a `fromJson` factory, and enable `strict-casts` so implicit `dynamic` downcasts show up in analysis. Invalid JSON text throws a `FormatException`.
code
dart · 17 linesimport 'dart:convert';
void main() {
const text =
'{"theme": "dark", "fontScale": 1, "pinned": ["java", "dart"], "version": 3}';
final data = jsonDecode(text); // dynamic
final map = data as Map<String, dynamic>; // fine: the decoder builds this type
// map['pinned'] as List<String>; // TypeError: it is a List<dynamic>
final pinned = (map['pinned'] as List).cast<String>();
// map['fontScale'] as double; // TypeError: 1 decodes as int
final fontScale = (map['fontScale'] as num).toDouble();
if (data case {'theme': String theme, 'version': int version}) {
print('$theme v$version $pinned $fontScale'); // dark v3 [java, dart] 1.0
}
}go deeper
Know that jsonDecode returns dynamic with maps and lists inside, and that you must cast values before using them as typed data.
Explain why as List<String> fails while cast<String>() or List.from works, the int-versus-double trap, and FormatException for bad text.
Validate at the boundary with patterns or fromJson factories, turn on strict-casts, and keep dynamic from leaking into widgets or business logic.
Decide where schema checking lives, generated models, hand-written parsers or server contracts, and how the app degrades when a payload does not match.
## What comes out of `jsonDecode` `jsonDecode` in `dart:convert` is shorthand for `json.decode`. Its declared return type is **`dynamic`**, and the `JsonDecoder` documentation lists what the value can contain: | JSON | Dart value | |---|---| | object `{...}` | `Map<String, dynamic>` | | array `[...]` | `List<dynamic>` | | string | `String` | | number | `int` for whole numbers, otherwise `double` | | `true` / `false` | `bool` | | `null` | `null` | The containers are created as `Map<String, dynamic>` and `List<dynamic>` regardless of what they hold. That runtime type is what every cast is checked against. ## Why casts are needed Dart's type system cannot see inside a JSON string, so `dynamic` switches off static checking. Code like `final List<String> tags = jsonDecode(text)['tags'];` compiles, because `dynamic` is implicitly downcast, and then fails when it runs. Three runtime failures account for most bugs: 1. **Generic list casts.** `decoded['pinned'] as List<String>` throws a `TypeError`, since the object's runtime type is `List<dynamic>` even if every element is a string. Use `(decoded['pinned'] as List).cast<String>()`, which returns a view that checks each element when read, or `List<String>.from(...)`, which copies and checks eagerly. 2. **Numbers.** JSON has one number type. `1` decodes as `int`, `1.0` and `1.2` as `double`, so `value as double` breaks as soon as a writer emits `1`. Read numbers as `num` and convert with `toDouble()` or `toInt()`. 3. **Missing or null keys.** `map['fontScale']` is `null` when the key is absent, and a non-nullable cast throws. Decide on defaults explicitly. Casting the top-level object with `as Map<String, dynamic>` does work, because that is exactly the map type the decoder creates. ## Cast idioms that work | Goal | Idiom | |---|---| | a required string | `map['theme'] as String` | | an optional string | `map['note'] as String?` | | any number as a double | `(map['fontScale'] as num).toDouble()` | | a list of strings | `(map['pinned'] as List).cast<String>()` or `List<String>.from(...)` | | a nested object | `map['display'] as Map<String, dynamic>` | | a map of ints | `Map<String, int>.from(map['limits'] as Map)` | Each idiom either succeeds with a correctly typed value or throws at the line that reads the field, which makes a bad payload easy to locate. ## Validating with patterns Dart 3 patterns make shape checks declarative. An `if-case` statement checks types, keys and structure at once and binds typed variables: - `if (data case {'theme': String theme, 'version': int version}) { ... }` confirms `data` is a map, both keys exist, and the values have the stated types. - A `switch` over the decoded value can route different payload shapes to different branches. - Anything that fails the pattern falls through to your error handling instead of throwing deep inside a widget. This is the dart.dev recommendation for data from external sources: validate the structure first rather than trusting it. ## Making the analyzer help - `analyzer: language: strict-casts: true` in `analysis_options.yaml` reports every implicit downcast from `dynamic`, such as passing `jsonDecode(text)` straight to a `List<String>` parameter. - Declaring decoded values as `Object?` instead of `dynamic` forces an explicit check or cast before use. - Model classes with `fromJson` factories, hand-written or generated, keep the casts in one place. ## Errors to expect - **Invalid JSON text**, such as a trailing comma or single quotes, makes `jsonDecode` throw a `FormatException`. - **Wrong shapes** surface as `TypeError`s at the first cast that disagrees, which may be far from the decode call. - Catch and report both at the boundary where data enters the app, so the rest of the code works with typed values. ## Summary for an interview Say that `jsonDecode` returns `dynamic` built from `Map<String, dynamic>`, `List<dynamic>` and primitives, explain why `as List<String>` fails while `cast` works, mention the `int` versus `double` trap, and show a pattern or `fromJson` validation step. That covers what interviewers mean when they ask why decoded JSON needs casts.
- What is the difference between list.cast<String>() and List<String>.from(list)?`cast<String>()` returns a lazy view over the original `List<dynamic>` that checks each element's type when it is read, so a bad element fails later, at access. `List<String>.from(list)` copies the elements into a new list and checks them all immediately, which fails early and gives an independent list.
- What happens when jsonDecode is given text with a trailing comma?It throws a `FormatException`, because trailing commas are not valid JSON. Catch it where the text enters the app, such as after reading a settings file, and fall back to defaults or report the corrupt file.
- How does strict-casts in analysis_options.yaml help with JSON code?With `strict-casts: true` the analyzer stops allowing implicit downcasts from `dynamic`. Passing `jsonDecode(text)` straight to a `List<String>` parameter becomes an error, so every conversion from decoded JSON has to be written explicitly, which is where the runtime failures would otherwise hide.
- jsonDecode returns a typed object matching the JSON's structure
- A JSON array of strings decodes to a List<String>
- Every JSON number decodes to a double
- Casting with as List<String> is the safe way to type a decoded list
- jsonDecode returns null for invalid JSON text