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
ja:JsonSerializable
. You can provide arguments toja:JsonSerializable
to configure the generated code. You can also customize individual fields by annotating them withja: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
ja: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
ja:JsonSerializable
:
Building creates the corresponding part example.g.dart
:
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.
With a Dart package, run dart run build_runner build
in the package directory.
With a Flutter package, run flutter pub run build_runner build
in your package
directory.
The only annotation required to use this package is ja: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
ja:JsonKey
annotating the target field. - Set properties on
ja:JsonSerializable
annotating the target type. - Add configuration to
build.yaml
– see below.
Every ja: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
ja:JsonSerializable
take precedence over settings in build.yaml
.
There is some overlap between settings on ja:JsonKey
and
ja:JsonSerializable
. In these cases, the property on ja:JsonKey
takes
precedence over any value set on ja:JsonSerializable
.
Annotate enum
types with ja:JsonEnum
(new in json_annotation
4.2.0) to:
- Specify the default rename logic for each enum value using
fieldRename
. For instance, usefieldRename: FieldRename.kebab
to encodeenum
valuenoGood
as"no-good"
. - Force the generation of the
enum
helpers, even if theenum
is not referenced in code. This is an edge scenario, but useful for some.
Annotate enum
values with ja:JsonValue
to specify the encoded value to map
to target enum
entries. Values can be of type core:String
or core:int
.
If you are annotating an
enhanced enum,
you can use ja:JsonEnum.valueField
to specify the field to use for the
serialized value.
Out of the box, json_serializable
supports many common types in the
dart:core
library:
The collection types –
– can contain values of all the above types.
For core:Map
, the key value must be one of
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 atoJson()
function to the type. Note: while you can usejson_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. - Use the
ja:JsonKey.toJson
andja: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. - Create an implementation of
ja:JsonConverter
and annotate either the corresponding field or the containing class.ja: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.
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_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