json_serializable 4.0.0 copy "json_serializable: ^4.0.0" to clipboard
json_serializable: ^4.0.0 copied to clipboard

outdated

Automatically generate code for converting to and from JSON by annotating Dart classes.

Pub Package

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. See the table below for details on the annotation values.

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

Setup #

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

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()
class Person {
  final String firstName;
  final String lastName;
  final DateTime? dateOfBirth;
  Person({required this.firstName, required this.lastName, this.dateOfBirth});
  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);
  Map<String, dynamic> toJson() => _$PersonToJson(this);
}

Building creates the corresponding part example.g.dart:

part of 'example.dart';

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

Map<String, dynamic> _$PersonToJson(Person instance) => <String, dynamic>{
      'firstName': instance.firstName,
      'lastName': instance.lastName,
      'dateOfBirth': instance.dateOfBirth?.toIso8601String(),
    };

Annotation values #

The only annotation required to use this package is @JsonSerializable. When applied to a class (in a correctly configured package), toJson and fromJson code will be generated when you build. There are three ways to control how code is generated:

  1. Set properties on @JsonSerializable.
  2. Add a @JsonKey annotation to a field and set properties there.
  3. Add configuration to build.yamlsee below.
build.yaml key JsonSerializable JsonKey
any_map JsonSerializable.anyMap
checked JsonSerializable.checked
create_factory JsonSerializable.createFactory
create_to_json JsonSerializable.createToJson
disallow_unrecognized_keys JsonSerializable.disallowUnrecognizedKeys
explicit_to_json JsonSerializable.explicitToJson
field_rename JsonSerializable.fieldRename
generic_argument_factories JsonSerializable.genericArgumentFactories
ignore_unannotated JsonSerializable.ignoreUnannotated
include_if_null JsonSerializable.includeIfNull JsonKey.includeIfNull
JsonKey.defaultValue
JsonKey.disallowNullValue
JsonKey.fromJson
JsonKey.ignore
JsonKey.name
JsonKey.required
JsonKey.toJson
JsonKey.unknownEnumValue

Note: every JsonSerializable field is configurable via build.yaml – see the table for the corresponding key. If you find you want all or most of your classes with the same configuration, it may be easier to specify values once in the YAML file. Values set explicitly on @JsonSerializable take precedence over settings in build.yaml.

Note: There is some overlap between fields on JsonKey and JsonSerializable. In these cases, if a value is set explicitly via JsonKey it will take precedence over any value set on JsonSerializable.

Build configuration #

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

targets:
  $default:
    builders:
      json_serializable:
        options:
          # Options configure how source code is generated for every
          # `@JsonSerializable`-annotated class in the package.
          #
          # The default value for each is listed.
          any_map: false
          checked: false
          create_factory: true
          create_to_json: true
          disallow_unrecognized_keys: false
          explicit_to_json: false
          field_rename: none
          generic_argument_factories: false
          ignore_unannotated: false
          include_if_null: true
3286
likes
0
pub points
99%
popularity

Publisher

verified publishergoogle.dev

Automatically generate code for converting to and from JSON by annotating Dart classes.

Repository (GitHub)
View/report issues

License

unknown (LICENSE)

Dependencies

analyzer, build, build_config, json_annotation, meta, path, source_gen

More

Packages that depend on json_serializable