Feature: add support for JsonSerializable.dateTimeUtc (#1557)

kevmoo · web-flow · commit fad91d99a2d6 · 2026-02-02T17:31:56.000-08:00
Fixes #1371
diff --git a/json_annotation/CHANGELOG.md b/json_annotation/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 4.11.0-wip
+
+- Add `JsonSerializable.dateTimeUtc` configuration option. 
+  ([#1371](https://github.com/google/json_serializable.dart/issues/1371))
+
 ## 4.10.0
 
 - Support `JsonKey` annotation on constructor parameters.
diff --git a/json_annotation/lib/src/json_serializable.dart b/json_annotation/lib/src/json_serializable.dart
@@ -129,6 +129,13 @@ class JsonSerializable {
   /// ```
   final bool? createToJson;
 
+  /// Whether the generator should use UTC time for [DateTime] fields.
+  ///
+  /// If `true`, all [DateTime] fields are written to JSON in UTC using
+  /// `DateTime.toUtc().toIso8601String()`.
+  /// If `false` (the default), `DateTime.toIso8601String()` is used.
+  final bool? dateTimeUtc;
+
   /// If `false` (the default), then the generated `FromJson` function will
   /// ignore unrecognized keys in the provided JSON [Map].
   ///
@@ -283,6 +290,7 @@ class JsonSerializable {
     this.converters,
     this.genericArgumentFactories,
     this.createPerFieldToJson,
+    this.dateTimeUtc,
   });
 
   factory JsonSerializable.fromJson(Map<String, dynamic> json) =>
diff --git a/json_annotation/lib/src/json_serializable.g.dart b/json_annotation/lib/src/json_serializable.g.dart
diff --git a/json_annotation/pubspec.yaml b/json_annotation/pubspec.yaml
@@ -1,5 +1,5 @@
 name: json_annotation
-version: 4.10.0
+version: 4.11.0-wip
 description: >-
   Classes and helper functions that support JSON code generation via the
   `json_serializable` package.
diff --git a/json_serializable/CHANGELOG.md b/json_serializable/CHANGELOG.md
@@ -1,5 +1,7 @@
-## 6.12.1-wip
+## 6.13.0-wip
 
+- Support `JsonSerializable.dateTimeUtc` configuration option. 
+  ([#1371](https://github.com/google/json_serializable.dart/issues/1371))
 - Remove `json_schema` from `dependencies` (it is only used in tests).
 
 ## 6.12.0
diff --git a/json_serializable/README.md b/json_serializable/README.md
@@ -319,6 +319,7 @@ targets:
           create_json_schema: false
           create_per_field_to_json: false
           create_to_json: true
+          date_time_utc: false
           disallow_unrecognized_keys: false
           explicit_to_json: false
           field_rename: none
@@ -350,15 +351,15 @@ targets:
 [`Enum`]: https://api.dart.dev/dart-core/Enum-class.html
 [`int`]: https://api.dart.dev/dart-core/int-class.html
 [`Iterable`]: https://api.dart.dev/dart-core/Iterable-class.html
-[`JsonConverter`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonConverter-class.html
-[`JsonEnum.valueField`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonEnum/valueField.html
-[`JsonEnum`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonEnum-class.html
-[`JsonKey.fromJson`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonKey/fromJson.html
-[`JsonKey.toJson`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonKey/toJson.html
-[`JsonKey`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonKey-class.html
-[`JsonLiteral`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonLiteral-class.html
-[`JsonSerializable`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonSerializable-class.html
-[`JsonValue`]: https://pub.dev/documentation/json_annotation/4.10.0/json_annotation/JsonValue-class.html
+[`JsonConverter`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonConverter-class.html
+[`JsonEnum.valueField`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonEnum/valueField.html
+[`JsonEnum`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonEnum-class.html
+[`JsonKey.fromJson`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/fromJson.html
+[`JsonKey.toJson`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/toJson.html
+[`JsonKey`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey-class.html
+[`JsonLiteral`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonLiteral-class.html
+[`JsonSerializable`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonSerializable-class.html
+[`JsonValue`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonValue-class.html
 [`List`]: https://api.dart.dev/dart-core/List-class.html
 [`Map`]: https://api.dart.dev/dart-core/Map-class.html
 [`num`]: https://api.dart.dev/dart-core/num-class.html
diff --git a/json_serializable/lib/src/check_dependencies.dart b/json_serializable/lib/src/check_dependencies.dart
@@ -15,7 +15,7 @@ const _annotationPkgName = 'json_annotation';
 final _supportLanguageRange = VersionConstraint.parse(
   supportedLanguageConstraint,
 );
-final requiredJsonAnnotationMinVersion = Version.parse('4.10.0');
+final requiredJsonAnnotationMinVersion = Version.parse('4.11.0-0');
 
 Future<void> pubspecHasRightVersion(BuildStep buildStep) async {
   final segments = buildStep.inputId.pathSegments;
diff --git a/json_serializable/lib/src/settings.dart b/json_serializable/lib/src/settings.dart
@@ -52,7 +52,7 @@ class Settings {
   /// If [typeHelpers] is not provided, the built-in helpers are used:
   /// [BigIntHelper], [DateTimeHelper], [DurationHelper], [JsonHelper], and
   /// [UriHelper].
-  Settings({JsonSerializable? config, List<TypeHelper>? typeHelpers})
+  Settings({required JsonSerializable? config, List<TypeHelper>? typeHelpers})
     : config = config != null
           ? ClassConfig.fromJsonSerializable(config)
           : ClassConfig.defaults,
diff --git a/json_serializable/lib/src/type_helpers/config_types.dart b/json_serializable/lib/src/type_helpers/config_types.dart
@@ -61,6 +61,7 @@ class ClassConfig {
   final bool createJsonKeys;
   final bool createPerFieldToJson;
   final bool createJsonSchema;
+  final bool dateTimeUtc;
   final bool disallowUnrecognizedKeys;
   final bool explicitToJson;
   final FieldRename fieldRename;
@@ -80,6 +81,7 @@ class ClassConfig {
     required this.createJsonKeys,
     required this.createPerFieldToJson,
     required this.createJsonSchema,
+    required this.dateTimeUtc,
     required this.disallowUnrecognizedKeys,
     required this.explicitToJson,
     required this.fieldRename,
@@ -108,6 +110,7 @@ class ClassConfig {
         createFactory:
             config.createFactory ?? ClassConfig.defaults.createFactory,
         createToJson: config.createToJson ?? ClassConfig.defaults.createToJson,
+        dateTimeUtc: config.dateTimeUtc ?? ClassConfig.defaults.dateTimeUtc,
         ignoreUnannotated:
             config.ignoreUnannotated ?? ClassConfig.defaults.ignoreUnannotated,
         explicitToJson:
@@ -121,7 +124,6 @@ class ClassConfig {
         disallowUnrecognizedKeys:
             config.disallowUnrecognizedKeys ??
             ClassConfig.defaults.disallowUnrecognizedKeys,
-        // TODO typeConverters = []
       );
 
   /// An instance of [JsonSerializable] with all fields set to their default
@@ -136,6 +138,7 @@ class ClassConfig {
     createJsonKeys: false,
     createPerFieldToJson: false,
     createJsonSchema: false,
+    dateTimeUtc: false,
     disallowUnrecognizedKeys: false,
     explicitToJson: false,
     fieldRename: FieldRename.none,
@@ -160,6 +163,7 @@ class ClassConfig {
     genericArgumentFactories: genericArgumentFactories,
     fieldRename: fieldRename,
     disallowUnrecognizedKeys: disallowUnrecognizedKeys,
+    dateTimeUtc: dateTimeUtc,
     // TODO typeConverters = []
   );
 }
diff --git a/json_serializable/lib/src/type_helpers/date_time_helper.dart b/json_serializable/lib/src/type_helpers/date_time_helper.dart
@@ -9,15 +9,15 @@ import '../default_container.dart';
 import '../type_helper.dart';
 import 'to_from_string.dart';
 
-class DateTimeHelper extends TypeHelper {
+class DateTimeHelper extends TypeHelper<TypeHelperContextWithConfig> {
   const DateTimeHelper();
 
   @override
   String? serialize(
     DartType targetType,
     String expression,
-    TypeHelperContext context,
-  ) => dateTimeString.serialize(
+    TypeHelperContextWithConfig context,
+  ) => context._dateTimeHelper.serialize(
     targetType,
     expression,
     targetType.isNullableType,
@@ -36,3 +36,8 @@ class DateTimeHelper extends TypeHelper {
     false,
   );
 }
+
+extension on TypeHelperContextWithConfig {
+  ToFromStringHelper get _dateTimeHelper =>
+      config.dateTimeUtc ? dateTimeUtcString : dateTimeString;
+}
diff --git a/json_serializable/lib/src/type_helpers/to_from_string.dart b/json_serializable/lib/src/type_helpers/to_from_string.dart
@@ -15,6 +15,12 @@ final dateTimeString = ToFromStringHelper(
   'DateTime',
 );
 
+final dateTimeUtcString = ToFromStringHelper(
+  'DateTime.parse',
+  'toUtc().toIso8601String()',
+  'DateTime',
+);
+
 final uriString = ToFromStringHelper('Uri.parse', 'toString()', 'Uri');
 
 /// Package-internal helper that unifies implementations of [Type]s that convert
diff --git a/json_serializable/lib/src/utils.dart b/json_serializable/lib/src/utils.dart
@@ -66,6 +66,7 @@ JsonSerializable _valueForAnnotation(ConstantReader reader) => JsonSerializable(
   createJsonKeys: reader.read('createJsonKeys').literalValue as bool?,
   createPerFieldToJson:
       reader.read('createPerFieldToJson').literalValue as bool?,
+  dateTimeUtc: reader.read('dateTimeUtc').literalValue as bool?,
   disallowUnrecognizedKeys:
       reader.read('disallowUnrecognizedKeys').literalValue as bool?,
   explicitToJson: reader.read('explicitToJson').literalValue as bool?,
@@ -129,6 +130,7 @@ ClassConfig mergeConfig(
     ctorParams: ctorParams,
     converters: converters.isNull ? const [] : converters.listValue,
     createJsonSchema: annotation.createJsonSchema ?? config.createJsonSchema,
+    dateTimeUtc: annotation.dateTimeUtc ?? config.dateTimeUtc,
   );
 }
 
diff --git a/json_serializable/pubspec.yaml b/json_serializable/pubspec.yaml
@@ -1,5 +1,5 @@
 name: json_serializable
-version: 6.12.1-wip
+version: 6.13.0-wip
 description: >-
   Automatically generate code for converting to and from JSON by annotating
   Dart classes.
@@ -23,7 +23,7 @@ dependencies:
 
   # Use a tight version constraint to ensure that a constraint on
   # `json_annotation` properly constrains all features it provides.
-  json_annotation: '>=4.10.0 <4.11.0'
+  json_annotation: '>=4.11.0-0 <4.12.0'
   meta: ^1.16.0
   path: ^1.9.0
   pub_semver: ^2.1.4
diff --git a/json_serializable/test/config_test.dart b/json_serializable/test/config_test.dart
@@ -176,6 +176,7 @@ const _invalidConfig = {
   'create_json_schema': 42,
   'create_per_field_to_json': 42,
   'create_to_json': 42,
+  'date_time_utc': 42,
   'disallow_unrecognized_keys': 42,
   'explicit_to_json': 42,
   'field_rename': 42,
diff --git a/json_serializable/test/json_serializable_test.dart b/json_serializable/test/json_serializable_test.dart
@@ -163,6 +163,7 @@ const _expectedAnnotatedTests = {
   'annotatedMethod',
   'theAnswer',
   'JsonSchemaTestClass',
+  'DateTimeUtcTestClass',
 };
 
 const _expectedSchemaTests = {
diff --git a/json_serializable/test/shared_config.dart b/json_serializable/test/shared_config.dart
@@ -18,16 +18,17 @@ final generatorConfigNonDefaultJson = Map<String, dynamic>.unmodifiable(
     checked: true,
     constructor: 'something',
     createFactory: false,
-    createToJson: false,
     createFieldMap: true,
     createJsonKeys: true,
+    createJsonSchema: true,
     createPerFieldToJson: true,
+    createToJson: false,
+    dateTimeUtc: true,
     disallowUnrecognizedKeys: true,
     explicitToJson: true,
     fieldRename: FieldRename.kebab,
+    genericArgumentFactories: true,
     ignoreUnannotated: true,
     includeIfNull: false,
-    genericArgumentFactories: true,
-    createJsonSchema: true,
   ).toJson(),
 );
diff --git a/json_serializable/test/src/_json_serializable_test_input.dart b/json_serializable/test/src/_json_serializable_test_input.dart
@@ -610,3 +610,19 @@ class JsonSchemaTestClass {
 
   JsonSchemaTestClass(this.name, this.age);
 }
+
+@ShouldGenerate(r'''
+DateTimeUtcTestClass _$DateTimeUtcTestClassFromJson(
+  Map<String, dynamic> json,
+) => DateTimeUtcTestClass(DateTime.parse(json['date'] as String));
+
+Map<String, dynamic> _$DateTimeUtcTestClassToJson(
+  DateTimeUtcTestClass instance,
+) => <String, dynamic>{'date': instance.date.toUtc().toIso8601String()};
+''')
+@JsonSerializable(dateTimeUtc: true)
+class DateTimeUtcTestClass {
+  final DateTime date;
+
+  DateTimeUtcTestClass(this.date);
+}
diff --git a/json_serializable/test/test_sources/test_sources.dart b/json_serializable/test/test_sources/test_sources.dart
@@ -18,6 +18,7 @@ class ConfigurationImplicitDefaults {
   createFieldMap: false,
   createJsonKeys: false,
   createPerFieldToJson: false,
+  dateTimeUtc: false,
   disallowUnrecognizedKeys: false,
   explicitToJson: false,
   fieldRename: FieldRename.none,
diff --git a/json_serializable/tool/readme/readme_template.md b/json_serializable/tool/readme/readme_template.md
@@ -176,6 +176,7 @@ targets:
           create_json_schema: false
           create_per_field_to_json: false
           create_to_json: true
+          date_time_utc: false
           disallow_unrecognized_keys: false
           explicit_to_json: false
           field_rename: none
