json_serializable

Description:

json serializable

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 {
/// The generated code assumes these values exist in JSON.
final String firstName, lastName;

/// The generated code below handles if the corresponding JSON value doesn't
/// exist or is empty.
final DateTime? dateOfBirth;

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

/// Connect the generated [_$PersonFromJson] function to the `fromJson`
/// factory.
factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);

/// Connect the generated [_$PersonToJson] function to the `toJson` method.
Map<String, dynamic> toJson() => _$PersonToJson(this);
}
copied to clipboard
Building creates the corresponding part example.g.dart:
part of 'example.dart';

Person _$PersonFromJson(Map<String, dynamic> json) => 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(),
};
copied to clipboard
Running the code generator #
Once you have added the annotations to your code you then need to run the code
generator to generate the missing .g.dart generated dart files.
Run dart run build_runner build in the package directory.
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:

Setting properties on JsonKey annotating the target field.
Set properties on JsonSerializable annotating the target type.
Add configuration to build.yaml – see below.

Every JsonSerializable field is configurable via build.yaml. 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.
There is some overlap between settings on JsonKey and
JsonSerializable. In these cases, the property on JsonKey takes
precedence over any value set on JsonSerializable.

Enums #
Annotate enum types with JsonEnum (new in json_annotation 4.2.0) to:

Specify the default rename logic for each enum value using fieldRename. For
instance, use fieldRename: FieldRename.kebab to encode enum value
noGood as "no-good".
Force the generation of the enum helpers, even if the enum is not
referenced in code. This is an edge scenario, but useful for some.

Annotate enum values with JsonValue to specify the encoded value to map
to target enum entries. Values can be of type String or int.
enum StatusCode {
@JsonValue(200)
success,
@JsonValue(301)
movedPermanently,
@JsonValue(302)
found,
@JsonValue(500)
internalServerError,
}
copied to clipboard
If you are annotating an
enhanced enum,
you can use JsonEnum.valueField to specify the field to use for the
serialized value.
@JsonEnum(valueField: 'code')
enum StatusCodeEnhanced {
success(200),
movedPermanently(301),
found(302),
internalServerError(500);

const StatusCodeEnhanced(this.code);
final int code;
}
copied to clipboard
Supported types #
Out of the box, json_serializable supports many common types in the
dart:core
library:
BigInt, bool, DateTime, double, Duration, Enum, int,
Iterable, List, Map, num, Object, Record, Set,
String, Uri
The collection types –
Iterable, List, Map, Record, Set
– can contain values of all the above types.
For Map, the key value must be one of
BigInt, DateTime, Enum, int, Object, String, Uri
Custom types and custom encoding #
If you want to use types that are not supported out-of-the-box or if you want to
customize the encoding/decoding of any type, you have a few options.


If you own/control the desired type, add a fromJson constructor and/or a
toJson() function to the type. Note: while you can use json_serializable
for these types, you don't have to! The generator code only looks for these
methods. It doesn't care how they were created.
@JsonSerializable()
class Sample1 {
Sample1(this.value);

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

// Sample2 is NOT annotated with @JsonSerializable(), but that's okay
// The class has a `fromJson` constructor and a `toJson` method, which is
// all that is required.
final Sample2 value;

Map<String, dynamic> toJson() => _$Sample1ToJson(this);
}

class Sample2 {
Sample2(this.value);

// The convention is for `fromJson` to take a single parameter of type
// `Map<String, dynamic>` but any JSON-compatible type is allowed.
factory Sample2.fromJson(int value) => Sample2(value);
final int value;

// The convention is for `toJson` to take return a type of
// `Map<String, dynamic>` but any JSON-compatible type is allowed.
int toJson() => value;
}
copied to clipboard


Use the JsonKey.toJson and JsonKey.fromJson properties to specify
custom conversions on the annotated field. The functions specified must be
top-level or static. See the documentation of these properties for details.
@JsonSerializable()
class Sample3 {
Sample3(this.value);

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

@JsonKey(
toJson: _toJson,
fromJson: _fromJson,
)
final DateTime value;

Map<String, dynamic> toJson() => _$Sample3ToJson(this);

static int _toJson(DateTime value) => value.millisecondsSinceEpoch;
static DateTime _fromJson(int value) =>
DateTime.fromMillisecondsSinceEpoch(value);
}
copied to clipboard


Create an implementation of JsonConverter and annotate either the
corresponding field or the containing class. JsonConverter is convenient
if you want to use the same conversion logic on many fields. It also allows
you to support a type within collections. Check out
these examples.
@JsonSerializable()
class Sample4 {
Sample4(this.value);

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

@EpochDateTimeConverter()
final DateTime value;

Map<String, dynamic> toJson() => _$Sample4ToJson(this);
}

class EpochDateTimeConverter implements JsonConverter<DateTime, int> {
const EpochDateTimeConverter();

@override
DateTime fromJson(int json) => DateTime.fromMillisecondsSinceEpoch(json);

@override
int toJson(DateTime object) => object.millisecondsSinceEpoch;
}
copied to clipboard


Build configuration #
Aside from 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
constructor: ""
create_factory: true
create_field_map: false
create_json_keys: false
create_per_field_to_json: false
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
copied to clipboard