dart_json_mapper 1.0.8

  • README.md
  • Example
  • Installing
  • Versions
  • 81


Build Status pub package

This package allows programmers to annotate Dart classes in order to Serialize / Deserialize them to / from JSON.


  • Compatible with all Dart platforms, including Flutter and Web platforms
  • No need to extend your classes from any mixins/base/abstract classes to keep code leaner
  • Clean and simple setup, transparent and straightforward usage with no heavy maintenance
  • No extra boilerplate involved, 100% generated only
  • Custom converters support per each class field

Basic setup

Library has NO dependency on dart:mirrors, one of the reasons is described here.

Dart classes reflection mechanism is based on reflectable library. This means "extended types information" is auto-generated out of existing Dart program guided by the annotated classes only, as the result types information is accesible at runtime, at a reduced cost.

Say, you have a dart program main.dart having some classes intended to be traveling to JSON and back.

  • First thing you should do is to put @jsonSerializable annotation on each of those classes
  • Next step is to auto generate main.reflectable.dart file. And afterwards import that file into main.dart


import 'package:dart_json_mapper/annotations.dart';
import 'package:dart_json_mapper/json_mapper.dart';

import 'main.reflectable.dart'; // Import generated code.

@jsonSerializable // This annotation let instances of MyData traveling to/from JSON
class MyData {
  int a = 123;

  @JsonProperty(ignore: true)
  bool b;

  @JsonProperty(name: 'd')
  String c;

  MyData(this.a, this.b, this.c);

main() {
  initializeReflectable(); // Imported from main.reflectable.dart
  print(JsonMapper.serialize(MyData(456, true, "yes")));
  // { 
  //  "a": 456,
  //  "d": "yes"
  // }

Now run the code generation step with the root of your package as the current directory:

> pub run dart_json_mapper:build lib/main.dart

where lib/main.dart should be replaced by the root library of the program for which you wish to generate code. You can generate code for several programs in one step; for instance, to generate code for a set of test files in test, this would typically be pub run dart_json_mapper:build test/*_test.dart. You'll need to re-run code generation each time you are making changes to lib/main.dart So for development time, use watch like this

> pub run dart_json_mapper:watch lib/main.dart

Each time you modify your project code, all *.reflectable.dart files will be updated as well.

  • Next step is to add "*.reflectable.dart" to your .gitignore
  • This is it, basic setup is done.

Example with immutable class

enum Color { Red, Blue, Green, Brown, Yellow, Black, White }

class Car {
    @JsonProperty(name: 'modelName')
    String model;
    @JsonProperty(enumValues: Color.values)
    Color color;
    @JsonProperty(ignore: true)
    Car replacement;
    Car(this.model, this.color);

class Immutable {
    final int id;
    final String name;
    final Car car;
    const Immutable(this.id, this.name, this.car);

    Immutable(1, 'Bob', Car('Audi', Color.Green))


 "id": 1,
 "name": "Bob",
 "car": {
  "modelName": "Audi",
  "color": "Color.Green"

Iterable based types handling

Since Dart language has no possibility to create typed iterables dynamically, it's a bit of a challenge to create exact typed lists/sets/etc via reflection approach. Those types has to be declared explicitly.

For example List() will produce List<dynamic> type which can't be directly set to the concrete target field List<Car> for instance. So obvious workaround will be to cast List<dynamic> => List<Car>, which can be performed as List<dynamic>().cast<Car>().

In order to do so, we'll use Value Decorator Function inspired by Decorator pattern.

final iterableCarDecorator = (value) => value.cast<Car>();
final String json = '[{"modelName": "Audi", "color": "Color.Green"}]';

List<Car> myCarsList = JsonMapper.deserialize(json);
Set<Car> myCarsSet = JsonMapper.deserialize(json);

Basic iterable based generics using Dart built-in types like List<num>, List<Sring>, List<bool>, List<DateTime>, Set<num>, Set<Sring>, Set<bool>, Set<DateTime>, etc. supported out of the box.

For custom iterable types like List<Car> / Set<Car> you have to register value decorator function as showed in a code snippet above before using deserialization. This function will have explicit cast to concrete iterable type.

Enum based types handling

Enum construction in Dart has a specific meaning, and has to be treated accordingly.

Enum declarations should not be annotated with @jsonSerializable, since they are not a classes technically, but a special built in types.

@JsonProperty(enumValues: Color.values)
Color color;

Each enum based class field has to be annotated as showed in a snippet above. Enum.values refers to a list of all possible enum values, it's a handy built in capability of all enum based types. Without providing all values it's not possible to traverse it's values properly.

Custom based types handling

For the very custom types, specific ones, or doesn't currently supported by this library, you can provide your own custom Converter class per each custom runtimeType.

/// Abstract class for custom converters implementations
abstract class ICustomConverter<T> {
  dynamic toJSON(T object, [JsonProperty jsonProperty]);
  T fromJSON(dynamic jsonValue, [JsonProperty jsonProperty]);

All you need to get going with this, is to implement this abstract class

class CustomStringConverter implements ICustomConverter<String> {
  const CustomStringConverter() : super();

  String fromJSON(dynamic jsonValue, [JsonProperty jsonProperty]) {
    return jsonValue;

  dynamic toJSON(String object, [JsonProperty jsonProperty]) {
    return '_${object}_';

And register it afterwards, if you want to have it applied for all occurrences of specified type


OR use it individually on selected class fields, via @JsonProperty annotation

@JsonProperty(converter: CustomStringConverter())
String title;

And this is it, you are all set and ready to go. Happy coding!

Feature requests and bug reports

Please file feature requests and bugs using the github issue tracker for this repository.


  • Fixnum types Int32, Int64 support added


  • Iterable based types support enhanced


  • Set based types support added


  • Uint8List, BigInt types support added


  • Value decorators support enhanced


  • Value decorator introduced


  • Added some docs
  • Added test on ignored class field


  • Improved Support for Map<K, V> type
  • Added basic Support for dynamic type


  • Positional constructor parameters support
  • Support for Symbol, Map types
  • More tests added


  • Support Dart 2.0
  • Support latest reflectable library changes
  • Remove dependency on barback


  • Converters registry introduced
  • Error handling improved


  • Converter auto detection based on field type
  • Update pubspec for Dart 2.0


  • Update readme
  • Immutable classes serialization / deserialization support


  • Tiny update to fix pubspec & readme


  • Circular reference detection during serialization added


  • Support Lists of Enums, Dates, Numbers etc.
  • @JsonSerializable() => @jsonSerializable


  • build & watch scripts added as a tooling for development time


  • DateConverter & NumberConverter introduced
  • Parameters for custom converter introduced


  • Convert Enum values to string by default, to skip a disordered values drawback with indexed enum values.
  • Enum's does not have to be annotated, since almost all of them are parts of third party libraries w/o access for modification.
  • dateTimeConverter introduced


  • Remove dependency on dart:mirrors.


  • First published release.


library json_mapper.example;

import 'package:dart_json_mapper/annotations.dart';
import 'package:dart_json_mapper/converters.dart';
import 'package:dart_json_mapper/json_mapper.dart';

import 'example.reflectable.dart'; // Import generated code.

enum Color { Red, Blue, Green, Brown, Yellow, Black, White }

class Car {
  @JsonProperty(name: 'modelName')
  String model;

  @JsonProperty(enumValues: Color.values)
  Color color;

  Car(this.model, this.color);

  String toString() {
    return 'Car{model: $model, color: $color}';

class Person {
  List<String> skills = ['Go', 'Dart', 'Flutter'];

  @JsonProperty(name: 'last_promotion_date', ignore: true)
  DateTime lastPromotionDate;

  @JsonProperty(name: 'hire_date')
  DateTime hireDate = DateTime(2003, 02, 28);

  bool married = true;
  String name = "Forest";

  @JsonProperty(ignore: true)
  num salary;

  num dob;
  num age = 36;
  var lastName = "Gump";

  @JsonProperty(name: 'eye_color', enumValues: Color.values)
  Color eyeColor = Color.Blue;

  @JsonProperty(enumValues: Color.values, converter: enumConverterNumeric)
  Color hairColor = Color.Brown;

  List<Car> vehicles = [Car("Tesla", Color.Black), Car("BMW", Color.Red)];

  String get fullName => "${name} ${lastName}";


  String toString() {
    return 'Person{skills: $skills, lastPromotionDate: '
        '$lastPromotionDate, hireDate: $hireDate, married: $married, name: '
        '$name, salary: $salary, dob: $dob, age: $age, lastName: $lastName, '
        'eyeColor: $eyeColor, hairColor: $hairColor, vehicles: $vehicles}';

void main() {

  final String personJson = '''{
 "skills": [
 "hire_date": "2003-02-28",
 "married": true,
 "name": "Forest",
 "dob": null,
 "age": 36,
 "lastName": "Gump",
 "eye_color": "Color.Blue",
 "hairColor": 3,
 "vehicles": [
   "modelName": "Tesla",
   "color": "Color.Black"
   "modelName": "BMW",
   "color": "Color.Red"

  // Serialize

  // Deserialize

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  dart_json_mapper: ^1.0.8

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:dart_json_mapper/annotations.dart';
import 'package:dart_json_mapper/converters.dart';
import 'package:dart_json_mapper/errors.dart';
import 'package:dart_json_mapper/json_mapper.dart';
Version Uploaded Documentation Archive
1.0.8 Sep 11, 2018 Go to the documentation of dart_json_mapper 1.0.8 Download dart_json_mapper 1.0.8 archive
1.0.7 Sep 10, 2018 Go to the documentation of dart_json_mapper 1.0.7 Download dart_json_mapper 1.0.7 archive
1.0.6 Sep 8, 2018 Go to the documentation of dart_json_mapper 1.0.6 Download dart_json_mapper 1.0.6 archive
1.0.5 Sep 5, 2018 Go to the documentation of dart_json_mapper 1.0.5 Download dart_json_mapper 1.0.5 archive
1.0.4 Sep 3, 2018 Go to the documentation of dart_json_mapper 1.0.4 Download dart_json_mapper 1.0.4 archive
1.0.3 Sep 2, 2018 Go to the documentation of dart_json_mapper 1.0.3 Download dart_json_mapper 1.0.3 archive
1.0.2 Sep 1, 2018 Go to the documentation of dart_json_mapper 1.0.2 Download dart_json_mapper 1.0.2 archive
1.0.1 Aug 27, 2018 Go to the documentation of dart_json_mapper 1.0.1 Download dart_json_mapper 1.0.1 archive
1.0.0 Aug 26, 2018 Go to the documentation of dart_json_mapper 1.0.0 Download dart_json_mapper 1.0.0 archive
0.1.3 Aug 19, 2018 Go to the documentation of dart_json_mapper 0.1.3 Download dart_json_mapper 0.1.3 archive

All 23 versions...

Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Dec 5, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.7


Detected platforms: Flutter, web, other

No platform restriction found in libraries.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
analyzer ^0.32.5 0.32.6 0.34.0
build ^0.12.7+3 0.12.8 1.0.1
build_config ^0.3.0 0.3.1+4
build_runner ^0.10.1+1 0.10.3 1.1.2
fixnum ^0.10.8 0.10.9
intl ^0.15.6 0.15.7
reflectable ^2.0.6 2.0.7 2.0.8
Transitive dependencies
args 1.5.1
async 2.0.8
build_resolvers 0.2.2+6
build_runner_core 1.0.0 1.1.1
built_collection 4.1.0
built_value 6.1.6
charcode 1.1.2
code_builder 3.1.3
collection 1.14.11
convert 2.0.2
crypto 2.0.6
csslib 0.14.6
dart_style 1.1.3 1.2.1
front_end 0.1.4+2 0.1.7
glob 1.1.7
graphs 0.1.3+1
html 0.13.3+3
http 0.12.0
http_multi_server 2.0.5
http_parser 3.1.3
io 0.3.3
js 0.6.1+1
json_annotation 1.2.0 2.0.0
kernel 0.3.4+2 0.3.7
logging 0.11.3+2
matcher 0.12.4
meta 1.1.6
mime 0.9.6+2
package_config 1.0.5
package_resolver 1.0.6
path 1.6.2
pedantic 1.3.0
plugin 0.2.0+3
pool 1.3.6
pub_semver 1.4.2
pubspec_parse 0.1.2+3
quiver 2.0.1
shelf 0.7.3+3
shelf_web_socket 0.2.2+4
source_span 1.4.1
stack_trace 1.9.3
stream_channel 1.6.8
stream_transform 0.0.14+1
string_scanner 1.0.4
timing 0.1.1+1
typed_data 1.1.6
utf 0.9.0+5
watcher 0.9.7+10
web_socket_channel 1.0.9
yaml 2.1.15
Dev dependencies
test ^1.3.0