json_serializable 0.5.7

  • README.md
  • Example
  • Installing
  • Versions
  • 96

Build Status

Provides Dart Build System builders for handling JSON.

The builders generate code when they find members annotated with classes defined in package:json_annotation.

  • To generate to/from JSON code for a class, annotate it with JsonSerializable. You can provide arguments to JsonSerializable to configure the generated code. You can also customize individual fields by annotating them with JsonKey and providing custom arguments.

  • To generate a Dart field with the contents of a file containting JSON, use the JsonLiteral annotation.

To configure your project for the latest released version of, json_serializable see the example.


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

import 'package:json_annotation/json_annotation.dart';

part 'example.g.dart';

@JsonSerializable(nullable: false)
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) {
  return new Person(
      firstName: json['firstName'] as String,
      lastName: json['lastName'] as String,
      dateOfBirth: 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()

Build configuration

Besides setting arguments on the associated annotation classes, you can also configure code generation by setting values in build.yaml.

          # Specifies a string to add to the top of every generated file.
          # If not specified, the default is the value of `defaultFileHeader`
          # defined in `package:source_gen/source_gen.dart`.
          # Note: use `|` to define a multi-line block.
          header: |
           // Copyright (c) 2018, the Dart project authors.


          # Options configure how source code is generated for every
          # `@JsonSerializable`-annotated class in the package.
          # The default value for each of them: `false`.
          # For usage information, reference the corresponding field in
          # `JsonSerializableGenerator`.
          use_wrappers: true
          any_map: true
          checked: true
          explicit_to_json: true
          generate_to_json_function: true


  • Added support for JsonKey.required.

    • When true, generated code throws a MissingRequiredKeysException if the key does not exist in the JSON map used to populate the annotated field.
    • Will be captured and wrapped in a CheckedFromJsonException if checked is enabled in json_serializable.
  • Added JsonKey.disallowNullValue.

    • When true, generated code throws a DisallowedNullValueException if the corresponding keys exist in in the JSON map, but it's value is null.
    • Will be captured and wrapped in a CheckedFromJsonException if checked is enabled in json_serializable.
  • Added support for Uri conversion.

  • Added missing checked parameter to the JsonSerializableGenerator.withDefaultHelpers constructor.

  • Added explicit_to_json configuration option.

    • See JsonSerializableGenerator.explicitToJson for details.
  • Added generate_to_json_function configuration option.

    • See JsonSerializableGenerator.generateToJsonFunction for details.


  • Added support for JsonSerializable.disallowUnrecognizedKeys.
    • Throws an UnrecognizedKeysException if it finds unrecognized keys in the JSON map used to populate the annotated field.
    • Will be captured and wrapped in a CheckedFromJsonException if checked is enabled in json_serializable.
  • All fromJson constructors now use block syntax instead of fat arrows.


  • Added support for JsonKey.defaultValue.

  • enum deserialization now uses helpers provided by json_annotation.

  • Small change to how nullable Map values are deserialized.

  • Small whitespace changes to JsonLiteral generation to align with dartfmt.

  • Improve detection of toJson and fromJson in nested types.


  • Fixed a bug introduced in 0.5.4 in some cases where enum values are nested in collections.


  • Add checked configuration option. If true, generated fromJson functions include extra checks to validate proper deserialization of types.

  • Added any_map to configuration. Allows fromJson code to support dynamic Map instances that are not explicitly Map<String, dynaimc>.

  • Added support for classes with type arguments.

  • Use Map.map for more map conversions. Simplifies generated code and fixes a subtle issue when the Map key type is dynamic or Object.


  • Require the latest version of package:analyzer - v0.32.0.

  • If JsonKey.fromJson function parameter is Iterable or Map with type arguments of dynamic or Object, omit the arguments when generating a cast. _myHelper(json['key'] as Map) instead of _myHelper(json['key'] as Map<dynamic, dynamic>).

  • JsonKey.fromJson/.toJson now support functions with optional arguments.


  • If JsonKey.fromJson/toJson are set, apply them before any custom or default TypeHelper instances. This allows custom DateTime parsing, by preempting the existing DateTime TypeHelper.


  • Support new fromJson and toJson fields on JsonKey.

  • Use log exposed by package:build. This requires end-users to have at least package:build_runner ^0.8.2.

  • Updated minimum package:source_gen dependency to 0.8.1 which includes improved error messages.


  • 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';

@JsonSerializable(nullable: false)
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);

Use this package as a library

1. Depend on it

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

  json_serializable: "^0.5.7"

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:json_serializable/json_serializable.dart';
Version Uploaded Documentation Archive
0.5.7 Jun 8, 2018 Go to the documentation of json_serializable 0.5.7 Download json_serializable 0.5.7 archive
0.5.6 Jun 1, 2018 Go to the documentation of json_serializable 0.5.6 Download json_serializable 0.5.6 archive
0.5.5 May 30, 2018 Go to the documentation of json_serializable 0.5.5 Download json_serializable 0.5.5 archive
0.5.4+1 May 24, 2018 Go to the documentation of json_serializable 0.5.4+1 Download json_serializable 0.5.4+1 archive
0.5.4 May 22, 2018 Go to the documentation of json_serializable 0.5.4 Download json_serializable 0.5.4 archive
0.5.3 May 15, 2018 Go to the documentation of json_serializable 0.5.3 Download json_serializable 0.5.3 archive
0.5.2 May 10, 2018 Go to the documentation of json_serializable 0.5.2 Download json_serializable 0.5.2 archive
0.5.1 May 10, 2018 Go to the documentation of json_serializable 0.5.1 Download json_serializable 0.5.1 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

All 27 versions...


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

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


Describes how popular the package is relative to other packages. [more]
93 / 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: other

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


  • 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.54 <2.0.0
analyzer ^0.32.0 0.32.1
build >=0.9.0 <0.13.0 0.12.6
build_config >=0.2.6 <0.4.0 0.3.0
json_annotation >=0.2.8 <0.2.9 0.2.8
meta ^1.1.0 1.1.5
path ^1.3.2 1.6.1
source_gen >=0.8.1 <0.9.0 0.8.2
Transitive dependencies
args 1.4.3
async 2.0.7
charcode 1.1.1
convert 2.0.1
crypto 2.0.5
csslib 0.14.4
front_end 0.1.1
glob 1.1.5
html 0.13.3+1
kernel 0.3.1
package_config 1.0.3
plugin 0.2.0+2
pub_semver 1.4.1
pubspec_parse 0.1.1
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+4
watcher 0.9.7+8
Dev dependencies
build_runner ^0.8.0
build_test >=0.9.0 <0.11.0
build_web_compilers ^0.4.0+1
collection ^1.14.0 1.14.10
dart_style ^1.0.0 1.1.0
logging ^0.11.3+1 0.11.3+1
test ^0.12.3
yaml ^2.1.13 2.1.14