json_serializable 0.5.0

  • README.md
  • Example
  • Installing
  • Versions
  • 95

Build Status

Provides source_gen Generators to create code for JSON serialization and deserialization.

See the example package to understand how to configure your project.

User defined and generated code

Given a library example.dart with an Person class annotated with @JsonSerializable():

import 'package:json_annotation/json_annotation.dart';

part 'example.g.dart';

class Person extends Object with _$PersonSerializerMixin {
  final String firstName;
  final String lastName;

  final DateTime dateOfBirth;

  Person({this.firstName, this.lastName, this.dateOfBirth});

  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);

Building creates the corresponding part example.g.dart:

part of 'example.dart';

Person _$PersonFromJson(Map<String, dynamic> json) => new Person(
    firstName: json['firstName'] as String,
    lastName: json['lastName'] as String,
    dateOfBirth: json['dateOfBirth'] == null
        ? null
        : DateTime.parse(json['dateOfBirth'] as String));

abstract class _$PersonSerializerMixin {
  String get firstName;
  String get lastName;
  DateTime get dateOfBirth;
  Map<String, dynamic> toJson() => <String, dynamic>{
        'firstName': firstName,
        'lastName': lastName,
        'dateOfBirth': dateOfBirth?.toIso8601String()


  • BREAKING Removed deprecated support for require_library_directive / requireLibraryDirective in build_runner configuration.

  • BREAKING Removed the deprecated generators.dart library.

  • BREAKING Removed jsonPartBuilder function from public API.

  • Support the latest package:source_gen.

  • Private and ignored fields are now excluded when generating serialization and deserialization code by using @JsonKey(ignore: true).

  • Throw an exception if a private field or an ignored field is referenced by a required constructor argument.

  • More comprehensive escaping of string literals.


  • Breaking The nullable parameter on TypeHelper.serialize and .deserialize has been removed. It is now exposed in SerializeContext and DeserializeContext abstract classes as a read-only property.

  • Potentially Breaking The metadata property on SerializeContext and DeserializeContext is now readonly. This would potentially break code that extends these classes – which is not expected.


  • Potentially Breaking Inherited fields are now processed and used when generating serialization and deserialization code. There is a possibility that the generated code may change in undesired ways for classes annotated for v0.3.

  • Avoid unnecessary braces in string escapes.

  • Use single quotes when generating code.


  • The require_library_directive option now defaults to false. The option will be removed entirely in 0.4.0.


  • Support the latest version of the analyzer package.


  • Expanded package:build support to allow version 0.12.0.


  • Add a build.yaml so the builder can be consumed by users of build_runner version 0.7.0.

  • Now requires a Dart 2.0.0-dev release.


  • NEW top-level library json_serializable.dart.

    • Replaces now deprecated generators.dart to access JsonSerializableGenerator and JsonLiteralGenerator.

    • Adds the jsonPartBuilder function to make it easy to create a PartBuilder, without creating an explicit dependency on source_gen.

  • BREAKING UnsupportedTypeError added a new required constructor argument: reason.

  • BREAKING The deprecated annotations.dart library has been removed. Use package:json_annotation instead.

  • BREAKING The arguments to TypeHelper serialize and deserialize have changed.

    • SerializeContext and DeserializeContext (new classes) are now passed instead of the TypeHelperGenerator typedef (which has been deleted).
  • JsonSerializableGenerator now supports an optional useWrappers argument when generates and uses wrapper classes to (hopefully) improve the speed and memory usage of serialization – at the cost of more code.

    NOTE: useWrappers is not guaranteed to improve the performance of serialization. Benchmarking is recommended.

  • Make null field handling smarter. If a field is classified as not nullable, then use this knowledge when generating serialization code – even if includeIfNull is false.


  • Throw an exception if a duplicate JSON key is detected.

  • Support the nullable field on the JsonSerializable class annotation.


  • Throw a more helpful error when a constructor is missing.


  • Moved the annotations in annotations.dart to package:json_annotations.

    • Allows package authors to release code that has the corresponding annotations without requiring package users to inherit all of the transitive dependencies.
  • Deprecated annotations.dart.


  • Write out toJson methods more efficiently when the first fields written are not intercepted by the null-checking method.


  • Simplify the serialization of Map instances when no conversion is required for values.

  • Handle int literals in JSON being assigned to double fields.


  • Enable support for enum values.
  • Added asConst to JsonLiteral.
  • Improved the handling of Dart-specific characters in JSON strings.


  • Upgrade to package:source_gen v0.7.0


  • When serializing classes that implement their own fromJson constructor, honor their constructor parameter type.


  • BREAKING Types are now segmented into their own libraries.

    • package:json_serializable/generators.dart contains Generator implementations.

    • package:json_serializable/annotations.dart contains annotations. This library should be imported with your target classes.

    • package:json_serializable/type_helpers.dart contains TypeHelper classes and related helpers which allow custom generation for specific types.

  • BREAKING Generation fails for types that are not a JSON primitive or that do not explicitly supports JSON serialization.

  • BREAKING TypeHelper:

    • Removed can methods. Return null from (de)serialize if the provided type is not supported.

    • Added (de)serializeNested arguments to (de)serialize methods allowing generic types. This is how support for Iterable, List, and Map is implemented.

  • BREAKING JsonKey.jsonName was renamed to name and is now a named parameter.

  • Added support for optional, non-nullable fields.

  • Added support for excluding null values when generating JSON.

  • Eliminated all implicit casts in generated code. These would end up being runtime checks in most cases.

  • Provide a helpful error when generation fails due to undefined types.


  • Fix homepage in pubspec.yaml.


  • Split off from source_gen.

  • Add /* unsafe */ comments to generated output likely to be unsafe.

  • Support (de)serializing values in Map.

  • Fix ordering of fields when they are initialized via constructor.

  • Don't use static members when calculating fields to (de)serialize.


// Copyright (c) 2017, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

// ignore_for_file: annotate_overrides, hash_and_equals
import 'package:json_annotation/json_annotation.dart';

part 'example.g.dart';

class Person extends Object with _$PersonSerializerMixin {
  final String firstName;
  final String lastName;

  final DateTime dateOfBirth;

  Person({this.firstName, this.lastName, this.dateOfBirth});

  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);

1. Depend on it

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

  json_serializable: "^0.5.0"

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 packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:json_serializable/json_serializable.dart';
Version Uploaded Documentation Archive
0.5.0 Apr 3, 2018 Go to the documentation of json_serializable 0.5.0 Download json_serializable 0.5.0 archive
0.4.0 Feb 23, 2018 Go to the documentation of json_serializable 0.4.0 Download json_serializable 0.4.0 archive
0.3.2 Feb 12, 2018 Go to the documentation of json_serializable 0.3.2 Download json_serializable 0.3.2 archive
0.3.1+2 Feb 3, 2018 Go to the documentation of json_serializable 0.3.1+2 Download json_serializable 0.3.1+2 archive
0.3.1+1 Jan 18, 2018 Go to the documentation of json_serializable 0.3.1+1 Download json_serializable 0.3.1+1 archive
0.3.1 Jan 4, 2018 Go to the documentation of json_serializable 0.3.1 Download json_serializable 0.3.1 archive
0.3.0 Dec 15, 2017 Go to the documentation of json_serializable 0.3.0 Download json_serializable 0.3.0 archive
0.2.5 Nov 2, 2017 Go to the documentation of json_serializable 0.2.5 Download json_serializable 0.2.5 archive
0.2.4+1 Oct 2, 2017 Go to the documentation of json_serializable 0.2.4+1 Download json_serializable 0.2.4+1 archive
0.2.4 Sep 27, 2017 Go to the documentation of json_serializable 0.2.4 Download json_serializable 0.2.4 archive

All 19 versions...


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

  • Dart: 2.0.0-dev.49.0
  • pana: 0.10.6


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


Detected platforms: Flutter, other

Primary library: package:json_serializable/json_serializable.dart with components: io, isolate, build.


  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • 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 >=2.0.0-dev.32 <2.0.0
analyzer >=0.29.10 <0.32.0 0.31.1 0.31.2-alpha.1
build >=0.9.0 <0.13.0 0.12.2
build_config ^0.2.1 0.2.6+1
cli_util ^0.1.0 0.1.2+1
json_annotation >=0.2.3 <0.2.4 0.2.3
logging ^0.11.3 0.11.3+1
path ^1.3.2 1.5.1
source_gen >=0.7.5 <0.9.0 0.8.1
Transitive dependencies
args 1.4.2
async 2.0.6
charcode 1.1.1
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
front_end 0.1.0-alpha.9 0.1.0-alpha.11
glob 1.1.5
html 0.13.3
isolate 1.1.0 2.0.0
kernel 0.3.0-alpha.9 0.3.0-alpha.11
meta 1.1.2
package_config 1.0.3
plugin 0.2.0+2
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+4
watcher 0.9.7+7
yaml 2.1.13
Dev dependencies
build_runner ^0.8.0
build_test >=0.9.0 <0.11.0
collection ^1.14.0 1.14.9
dart_style ^1.0.0 1.0.9+1 1.0.10
test ^0.12.3