dart-json-mapper

pub package

Serialize / Deserialize Dart Objects to / from JSON

This package allows programmers to annotate Dart classes in order to serialize / deserialize them from / to JSON.

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

lib/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;

  // Important! Constructor must not have any required parameters.
  MyData([this.a, this.b, this.c]);
}

main() {
  initializeReflectable(); // Imported from main.reflectable.dart
  
  print(JsonMapper.serialize(new 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

  enum Color { Red, Blue, Green, Brown, Yellow, Black, White }
  
  @jsonSerializable
  class Car {
    @JsonProperty(name: 'modelName')
    String model;
  
    @JsonProperty(enumValues: Color.values)
    Color color;
  
    @JsonProperty(type: Car)
    Car replacement;
  
    Car([this.model, this.color]);
  }
  
  @jsonSerializable
  class Immutable {
    final int id;
    final String name;
    final Car car;
  
    Immutable({this.id, this.name, this.car});
  }
  
  print(
      JsonMapper.serialize(
        new Immutable(id: 1, name: 'Bob', car: new Car('Audi', Color.Green))
      )
  );

Output:

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

Why is this library exists?

When there are so many alternatives out there

It would be nice to have a Json serialization/deserialization library

  • Compatible with all Dart platforms, including Flutter and Web platforms.
  • No need to extend target classes from any mixins/base/abstract classes to keep code cleaner
  • Clean and simple setup, transparent and straightforward usage with no heavy maintanance involved
  • No extra boilerplate code involved
  • Custom converters support per each target class field

But, as of today we have...

| Name | Web + Flutter support | Concerns | | ----------- |:-----------------------:|:-----------|
|json_object_lite| yes | Target class has to be inherited from JsonObjectLite + boilerplate code | |jaguar_serializer| yes | Tons of boilerplate, personal serializer generated per each target class, unnecessary abstraction - "model"| |nomirrorsmap| yes | Cumbersome usage| |dson_core| no | | |dson| yes | Requires target class to be inherited from mixin + too much different unobvious annotations, like @ignore, @cyclical, @uid, etc| |dartson| no | | |json_god| no | | |jaguar_json| no | | |serializer_generator| no | | |dynamo| yes |Produces JSON output with type information injected in it| |serialization|yes |Cumbersome configuration and setup, will require continuous maintenance| |serializable| yes |Requires target class to be inherited from mixin, no custom logic allowed| |json_annotation|yes |Depends on json_serializable which is not compatible with Flutter| |json_serializable| no || |json_mapper| no || |built_value| yes |Over engineered solution, boilerplate, yes it's auto generated, but it is still boilerplate! enforces Immutability for all models, imply own patterns on your code base, too much responsibility in one library |

Feature requests and bug reports

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

Libraries

json_mapper
json_mapper.annotations
json_mapper.converters