json_annotation
4.12.0, released 6 months ago by google.dev
Provides annotations for json_serializable to generate JSON (de)serialization code.
What it does
Defines annotation classes like @JsonSerializable and @JsonKey that json_serializable reads to produce boilerplate for converting Dart objects to and from JSON. It does not contain any runtime logic itself.
AI-written summary of version 4.12.0, based on the package's README and metadata. Report an inaccuracy
Use it when
- You need compile‑time JSON (de)serialization without writing manual toJson/fromJson code.
- You are already using json_serializable or want a lightweight annotation package.
Skip it when
- You prefer runtime reflection‑based JSON handling (e.g., json_annotation is not needed).
- You target platforms where code generation is not possible.
Strengths
- Small, zero‑runtime‑overhead package.
- Works with Dart 3 and newer SDKs.
- Provides fine‑grained control via JsonKey options.
Weaknesses
- Requires a separate code‑gen step with build_runner and json_serializable.
- Only useful when paired with a generator; on its own it does nothing.
Setup
- Kind
- Pure Dart
- Effort
- Low
- Code generation
- No
- Direct dependencies
- 1
Add json_annotation to pubspec, then run build_runner with json_serializable (e.g., flutter pub run build_runner build).
import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';
@JsonSerializable()
class User {
final String name;
final int age;
User(this.name, this.age);
factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
Map<String, dynamic> toJson() => _$UserToJson(this);
}Alternatives
Packages that do the same job and could replace json_annotation.
- copy_with_extension_gen
Generate type‑safe copyWith extensions for annotated classes and record typedefs.
85Compare - build
Package for authoring build_runner compatible code generators.
87Compare - dart_mappable
JSON serialization and data classes generator supporting generics, inheritance, and customization.
89Compare - copy_with_extension
Annotation for generating copyWith extensions code using copy_with_extension_gen.
87Compare
Works with
Packages commonly used together with json_annotation: ones it builds on, ones built on it, and its own family.
- pubspec_parseBuilt on json_annotationParse pubspec.yaml files with a type‑safe API and detailed error reporting.
- checked_yamlBuilt on json_annotationProvides checkedYamlDecode to give detailed errors when decoding YAML with json_serializable.
- build_configBuilt on json_annotationFormat definition and support for parsing build.yaml configuration.
- build_runnerBuilt on json_annotationA build system for Dart code generation and modular compilation.
- freezed_annotationBuilt on json_annotationAnnotations for the freezed code-generator.
- json_serializableBuilt on json_annotationAutomatically generate code for converting Dart classes to and from JSON.
- flutter_launcher_iconsBuilt on json_annotationSimplifies the task of updating your Flutter app's launcher icon across platforms.
- freezedBuilt on json_annotationCode generation for immutable classes, tagged unions, and cloning without boilerplate.