json 0.20.1

json: ^0.20.1 copied to clipboard

This package supports easy encoding and decoding of JSON maps (maps of type Map<String, Object?>). It relies on a macro, that when applied to a user-defined Dart class, auto-generates a fromJson decoding constructor and a toJson encoding method.

Both the package itself, and the underlying macros language feature, are considered experimental. Thus they have incomplete functionality, may be unstable, have breaking changes as the feature evolves, and are not suitable for production code.

Applying the JsonCodable macro #

To apply the JsonCodable macro to a class, add it as an annotation:

import 'package:json/json.dart';

@JsonCodable()
class User {
  final String name;

  final int? age;
}

The macro generates two members for the User class: a fromJson constructor and a toJson method, with APIs like the following:

class User {
  User.fromJson(Map<String, Object?> json);

  Map<String, Object?> toJson();
}

Each non-nullable field in the annotated class must have an entry with the same name in the json map, but nullable fields are allowed to have no key at all. The toJson will omit null fields entirely from the map, and will not contain explicit null entries.

Extending other classes #

You are allowed to extend classes other than Object, but they must have a valid toJson method and fromJson constructor, so the following is allowed:

@JsonCodable()
class Manager extends User {
  final List<User> reports;
}

Supported field types #

All native JSON types are supported (int, double, String, bool, Null).

The core collection types List, Set, and Map are also supported, if their elements are supported types. For elements which require more than just a cast, the type must be statically provided through a generic type argument on the collection in order for the specialized code to be generated.

Additionally, custom types with a toJson method and fromJson constructor are allowed, including as generic type arguments to the collection types.

Generics #

Classes with generic type parameters are not supported, but may be in the future.

Configuration #

Macro configuration is a feature we intend to add, but it is not available at this time.

Because of this, field names must exactly match the keys in the maps, and default values are not supported.

Enabling the macros experiment #

Most tools accept the --enable-experiment=macros option, and appending that to your typical command line invocations should be all that is needed. For example, you can launch your flutter project like: flutter run --enable-experiment=macros.

For the analyzer, you will want to add some configuration to an analysis_options.yaml file at the root of your project:

analyzer:
  enable-experiment:
    - macros

Note that dart run is a little bit special, in that the option must come immediately following dart and before run - this is because it is an option to the Dart VM, and not the Dart script itself. For example, dart --enable-experiment=macros run bin/my_script.dart. This is also how the test package expects to be invoked, so dart --enable-experiment=macros test.