fix(core): serialize format: date as a calendar date

[barney-ws]

Problem

format: date maps to DateTime, the same as format: date-time, and json_serializable then encodes it with toIso8601String(). So a field the spec declares as a calendar date goes out as a full timestamp:

fromDate:
  type: string
  format: date
  pattern: '^\d{4}-\d{2}-\d{2}$'   # what the server actually validates

// generated
'fromDate': instance.fromDate.toIso8601String(),   // "2026-05-12T00:00:00.000"

The server rejects it as an invalid ISO date. We hit this on a PDF export endpoint whose fromDate / toDate query parameters are format: date; the same spec has date fields on request bodies and an array of them in a payload object, so it is not limited to query strings.

Change

Date properties and date query parameters get a _DateOnlyConverter, emitted into the files that need one:

class _DateOnlyConverter implements JsonConverter<DateTime, String> {
  const _DateOnlyConverter();

  @override
  DateTime fromJson(String json) => DateTime.parse(json);

  @override
  String toJson(DateTime date) =>
      '${date.year.toString().padLeft(4, '0')}-'
      '${date.month.toString().padLeft(2, '0')}-'
      '${date.day.toString().padLeft(2, '0')}';
}

json_serializable applies a JsonConverter to nullable fields and to lists by itself, so this one covers DateTime, DateTime? and List<DateTime> — I checked the generated .g.dart rather than assuming it.

DateTime stays the Dart type either way, so this only changes the encoding — nothing that reads these fields today has to change. date-time is untouched.

One plumbing fix went with it: query parameters lost their schema format on the way into the params generator, so the annotation could never have reached them.

Verification

Generated a spec covering required / nullable / list format: date, a date-time control and a format: date query parameter, then ran build_runner over the output and encoded it for real:

model  -> {"date":"2026-05-12","maybeDate":"2026-01-02","dates":["2026-03-04"],"createdAt":"2026-05-12T09:30:00.000Z"}
params -> {"fromDate":"2026-05-12","at":"2026-05-12T09:30:00.000Z"}
decode -> 2026-05-12 00:00:00.000 | [2026-03-04 00:00:00.000]

Dates come out as YYYY-MM-DD, date-time keeps its timestamp, and decoding still works.

5 tests added in models-date-format.test.ts, covering the annotation on required / nullable / list properties, date-time staying unannotated, no converter emitted for models without date fields, and the query-parameter path. packages/core: 40 files / 413 tests pass.

Notes

This is the third defect of the same kind, after numeric enums (#4) and boolean enums (#6): the Dart type is right, but the spec's format is lost by the time the value is serialized. All three are invisible to dart analyze — the generated code compiles and sends the wrong thing — which is the case for the round-trip assertions discussed on #4.

The 3 pre-existing no-unused-vars lint errors in headers-generator.* and getters/body.ts are still there, untouched.

[qwlong]

Review

Built the branch (413 tests pass), generated from a spec covering every shape this touches, and put the output through freezed 3.x + json_serializable 6.14 on Dart 3.9. The fix is correct and the claims in the description hold up under checking.

Verified

The converter reaches everything it should. Generating a model with required / nullable / list date properties, a date-time control, an inline nested object, and date path / query / header parameters:

Location	@_DateOnlyConverter()
required DateTime date	✅
DateTime? maybeDate	✅
List<DateTime>? dates	✅
inline nested object property	✅ (via the getters/object.ts path)
query parameter	✅
DateTime? createdAt (date-time)	✅ correctly untouched

The nullable/list claim is real. The generated .g.dart confirms json_serializable wraps a non-nullable JsonConverter on its own rather than rejecting it:

date: const _DateOnlyConverter().fromJson(json['date'] as String),
dates: (json['dates'] as List<dynamic>?)
    ?.map((e) => const _DateOnlyConverter().fromJson(e as String)),
'dates': instance.dates?.map(const _DateOnlyConverter().toJson).toList(),
'createdAt': instance.createdAt?.toIso8601String(),

Worth calling out given the last two PRs — this is exactly the layer that rejected @JsonValue(1.5) and @JsonValue(true) on #6, and here it accepts what's being generated. Checking the .g.dart rather than assuming was the right instinct.

Timezones are handled correctly. date.year/.month/.day are frame-dependent, so I went after this specifically. Dart's getters respect the isUtc flag, and the round trip that matters — server "2026-05-12" → fromJson → toJson — is stable under TZ=UTC, Pacific/Kiritimati (+14), Pacific/Midway (-11) and America/New_York, because DateTime.parse on a bare date yields a local, non-UTC value whose components can't drift. DateTime.utc(2026,5,12) also reports 2026-05-12 in every zone. The only case that shifts is a caller explicitly doing .toLocal() on a UTC instant across a date boundary, which is the caller moving the date, not the converter. padLeft(4) handles year < 1000 (0999-01-02).

One gap: header parameters

case 'query' carries the format now, but case 'header' right below it doesn't, and HeaderParameter has no format field. Details inline — same defect, same switch statement, not fixed.

Path parameters are genuinely fine, for the record: format: date there generates as String and is interpolated directly, so there's no DateTime to mis-encode.

Minor

The converter is emitted into every file that needs it — 3 copies in my sample. It's library-private per file so there's no conflict, and the build confirms it, but a shared models/date_only_converter.dart would avoid the duplication if you'd rather have one definition. Purely a style call.

On the framing in the description

Agreed this is the third instance of the same class, though it's worth separating them: numeric enums (#4) were a genuine wrong-wire-format bug like this one, whereas the boolean branch on #6 can't reach the wire at all — json_serializable rejects @JsonValue(true) at build time. This PR is the first of the three where the generated code both compiles and round-trips correctly end to end, which the round-trip assertions in the description actually demonstrate. That's the bar the CI changes discussed on #4 would enforce; main still has || true on build_runner, dart analyze and dart test, so none of this is being checked automatically yet.

[qwlong]

Re-review of 26a6c9c8 and 8db5f215

Rebuilt, 421 tests passing, and generated a full API then built it with freezed 3.x + json_serializable 6.14 on Dart 3.9. The header gap is closed, and the two commits fixed more than I'd reported.

Headers

Both renderers are covered, and the annotation survives all the way into the generated serializer:

// models/headers/export_pdf_headers.f.dart
@_DateOnlyConverter()
required DateTime xEffectiveDate,
required String xTenant,

// export_pdf_headers.f.g.dart
'X-Effective-Date': const _DateOnlyConverter().toJson(instance.xEffectiveDate),

Covering HeadersGenerator as well as ParamsGenerator is the part I'd have missed — I only ever exercised the default path, so a fix to that one alone would have looked complete from where I was standing.

The array query parameter bug I walked past

Replacing format?: string with dateOnly?: boolean computed through TypeMapper.isDateOnlySchema(p.schema) fixes something my last review didn't catch: the old param.format === 'date' only ever saw a scalar's own format, so an array of dates never matched. My check used a scalar query parameter and therefore missed it entirely. Now:

@_DateOnlyConverter()
List<DateTime>? days,

// .g.dart
'days': instance.days?.map(const _DateOnlyConverter().toJson).toList(),

Same for isDateOnlySchema(propDetails) → (propSchema) in model-generator.ts — that one was reading a shape that had already lost the nesting.

Also verified

• The converter actually reaches the wire for query parameters. An annotation json_serializable honours is worth nothing if the query path sidesteps toJson(), so I checked: toQueryParameters() opens with final json = toJson(); and flattens from there, and the service passes its result straight to Dio. It applies.
• $ref returning false is correctly reasoned. A $ref to a scalar {type: string, format: date} component generates class CalDate and the property comes out CalDate?, not DateTime — so there's no DateTime to annotate and nothing is lost by not following the ref, exactly as the comment claims.
• Everything builds. Model, nested inline object, params and headers together: build_runner wrote all outputs, dart analyze reports No issues found.
• Extracting the converter into a shared partial removes the per-file duplication I'd noted, and the doc comment now spells out the timezone caveat — including the DateTime(2026, 5, 13).toUtc() case, which is the one that will actually bite someone.

Nothing further from me on this one.

[barney-ws]

So is it ready to merge? @qwlong