[REQ][dart-dio] Support useOptional / patchOnly with serializationLibrary=freezed
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 42/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- dart
Research direction
Read the prior change in #25250 and inspect the Dart Dio generator’s Freezed templates and tests for useOptional and patchOnly; the payload does not name specific files. Prototype the proposed Freezed-specific Optional<T> serialization and check generated code for absent, explicit null, and present values, including the stated defaults and unknown enum behavior. Done when those cases work for wrapped properties while unaffected Freezed output remains unchanged.
Written by the indexing model from the issue text.
Description
Is your feature request related to a problem? Please describe.
Since #25250 added serializationLibrary=freezed (beta), useOptional and patchOnly are ignored under freezed and a warning is logged.
Freezed models declare every optional property as T? with includeIfNull: false. A PATCH body therefore cannot express the three states that partial updates need (JSON Merge Patch, RFC 7396):
| Intent | JSON |
|---|---|
| Leave unchanged | key omitted |
| Clear the field | "field": null |
| Set the field | "field": "value" |
With a plain T?, null can only mean one of the first two. Today it means "omit", so clients cannot clear a field. Switching to includeIfNull: true would instead send null for every unset field and wipe data on the server.
Describe the solution you'd like
Support useOptional / patchOnly with freezed, using the same Optional<T> API (Optional.absent() / Optional.present(value)) as the built_value and json_serializable backends:
UpdateItem(name: 'x') // {"name":"x"}
UpdateItem(name: 'x', imageId: Optional.present(null)) // {"name":"x","imageId":null}
UpdateItem(name: 'x', imageId: Optional.present('i')) // {"name":"x","imageId":"i"}
UpdateItem.fromJson({'name': 'x', 'imageId': null}).imageId // Optional.present(null)
UpdateItem.fromJson({'name': 'x'}).imageId // Optional.absent()
Proposed design (prototyped with freezed 3.2.5 / json_serializable 6.14, Dart 3.13):
- A freezed-specific
optional.dartin whichOptional<T>follows json_serializable's generic-helper protocol,Optional.fromJson(json, fromJsonT)/toJson(toJsonT). json_serializable then generates the inner conversion itself for enums,DateTime, nested models, lists and maps. Optional.absent()serializes to a private sentinel. Affected models use@Freezed(toJson: false)with a factory-level@JsonSerializable(createToJson: true), and their owntoJson()strips sentinel keys. WithouttoJson: false, freezed generates atoJson()that bypasses the stripping.@JsonKey(readValue: readOptionalValue)distinguishes a missing key from an explicitnull. json_serializable otherwise readsnullas absent.- Only models with wrapped properties change. All other freezed output, including the existing samples, is unchanged.
Decisions worth reviewing:
- Spec defaults. A wrapped property with a
defaultstarts asOptional.absent(), notOptional.present(default), because sending the default in a PATCH would overwrite server state. json_serializable currently usespresent(default). enumUnknownDefaultCase. It is not applied to wrapped enum fields, because json_serializable rejectsunknownEnumValueonOptional<Enum?>. Unknown values throw.- Binary properties are never wrapped; they are excluded from JSON anyway.
patchOnlyscope is unchanged: only schemas$ref'd directly by a PATCH request body are wrapped.- Out of scope: operation parameters (path, query, header, form) stay unwrapped, as with the other backends. Clearing a
multipart/form-datafield is not addressed, because form data has nonull.
Describe alternatives you've considered
- Reusing the shared
optional.mustache/OptionalConverter<T>. json_serializable does not apply a generic converter to concrete types such asOptional<String?>. WithserializationLibrary=json_serializableanduseOptional=true,build_runnercurrently fails withCould not generate fromJson code for ... To support the type Optional ...(separate bug report to follow). includeIfNull: falseon wrapped fields. json_serializable cannot omit a key based on its value, so this also dropsOptional.present(null).- Sending the full object (PUT-style) with
includeIfNull: true. This works only when the client always has the complete current state, sends more data, and can overwrite concurrent edits.
Additional context
Follow-up to #25250. I would like to implement this and can open a PR if the approach looks good.
- Dominant language
- Java
- Stars
- 26.9k
- Forks
- 7.8k
- Avg merge
- 2d 23m
- Merged PRs (30d)
- 177
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from OpenAPITools/openapi-generator
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
OpenAPITools/openapi-generator#25768 ·
Maintainers usually reply within 1 day
-
Enhancement: Feature
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
OpenAPITools/openapi-generator#25753 ·
Maintainers usually reply within 1 day
-
[BUG][RUBY-NEXTGEN] A non-String value in a pattern-constrained attribute raises NoMethodErrorPossibly taken @Inf1mum claimed this 2 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
OpenAPITools/openapi-generator#25724 · 1 comment ·
Maintainers usually reply within 1 day
-
[BUG][RUBY-NEXTGEN] Response#to_hash is advertised and raises when the data is an ArrayPossibly taken @Inf1mum claimed this 2 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
OpenAPITools/openapi-generator#25723 · 1 comment ·
Maintainers usually reply within 1 day
-
[BUG][RUBY-NEXTGEN] A JSON string response raises ApiError because the body is parsed twicePossibly taken @Inf1mum claimed this 2 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
OpenAPITools/openapi-generator#25719 · 1 comment ·
Maintainers usually reply within 1 day
All issues in OpenAPITools/openapi-generator
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
eclipse-tradista/tradista#371 ·
Maintainers usually reply within 1 day
-
critical
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
mars-sim/mars-sim#2199 · 2 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
projeto-ong-amar/projeto-ong-amar-backend#26 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
primefaces/primefaces#15568 ·
Maintainers usually reply within 1 day
-
崩溃日志只按 CRLF 分行Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
PCL-Community/PCL-CE#3872 ·
Maintainers usually reply within 1 day