dart_json_mapper 0.0.8

  • README.md
  • Example
  • Installing
  • Versions
  • new46


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 string in one line of code.

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;

  // 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.

Feature requests and bug reports

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


  • 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', converter: dateConverter)
  DateTime hireDate = new 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;

  @JsonProperty(type: Car)
  List<Car> vehicles = [
    new Car("Tesla", Color.Black),
    new 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
  print(JsonMapper.serialize(new Person()));

  // Deserialize
  print(JsonMapper.deserialize(personJson, Person));

Use this package as a library

1. Depend on it

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

  dart_json_mapper: "^0.0.8"

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub 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/json_mapper.dart';
Version Uploaded Documentation Archive
0.0.8 Jun 1, 2018 Go to the documentation of dart_json_mapper 0.0.8 Download dart_json_mapper 0.0.8 archive
0.0.7 May 31, 2018 Go to the documentation of dart_json_mapper 0.0.7 Download dart_json_mapper 0.0.7 archive
0.0.6 May 30, 2018 Go to the documentation of dart_json_mapper 0.0.6 Download dart_json_mapper 0.0.6 archive
0.0.5 May 29, 2018 Go to the documentation of dart_json_mapper 0.0.5 Download dart_json_mapper 0.0.5 archive
0.0.4 May 28, 2018 Go to the documentation of dart_json_mapper 0.0.4 Download dart_json_mapper 0.0.4 archive
0.0.3 May 27, 2018 Go to the documentation of dart_json_mapper 0.0.3 Download dart_json_mapper 0.0.3 archive
0.0.2 May 27, 2018 Go to the documentation of dart_json_mapper 0.0.2 Download dart_json_mapper 0.0.2 archive
0.0.1 May 27, 2018 Go to the documentation of dart_json_mapper 0.0.1 Download dart_json_mapper 0.0.1 archive
0.0.0 May 27, 2018 Go to the documentation of dart_json_mapper 0.0.0 Download dart_json_mapper 0.0.0 archive


We analyzed this package on Jun 12, 2018, and provided a score, details, and suggestions below. Analysis was completed with status tool failures using:

  • Dart: 2.0.0-dev.60.0
  • pana: 0.11.3


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


Detected platforms: unsure

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.


  • Fix dependencies in pubspec.yaml.

    Running pub upgrade failed with the following output:

    ERR: The current Dart SDK version is 2.0.0-dev.60.0.
     Because dart_json_mapper requires SDK version >=1.12.0 <=2.0.0-dev.58.0, version solving failed.
  • Fix platform conflicts.

    Error(s) prevent platform classification:

    Fix dependencies in pubspec.yaml.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.12.0 <=2.0.0-dev.58.0