RFC: emit option-typed fields as optional properties in TypeScript clients

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- TypeScript codegen now emits option-typed fields (`std::option::Option<T>` and `reflectapi::Option<T>`) as optional interface properties (`field?: T | null`) regardless of `#[serde(default)]` / `skip_serializing_if` annotations. serde accepts a missing key for option-typed fields unconditionally, so generated clients no longer force callers to pass explicit nulls. This matches the Python backend's behavior.
+- The exception is fields with a custom serde deserializer: `#[serde(deserialize_with = ...)]` / `#[serde(with = ...)]` without `#[serde(default)]` rejects a missing key, so such fields stay required. This also fixes the Python backend, which previously generated those fields as omittable keys the server rejects. A custom serializer alone (`serialize_with`) does not affect key optionality.
+- Schema format: `Field` gains two additive flags, `serialize_with` and `deserialize_with`, recording the presence of the corresponding serde attributes (`with` sets both; omitted from the JSON when false). Code constructing `reflectapi_schema::Field` with exhaustive struct literals needs the new fields.
+- Internals: field key-presence/nullability resolution now lives in one shared codegen schema pass (`resolve_field_wire_contract`) consumed by the TypeScript and Python backends, instead of per-backend heuristics.
+
 ## 0.17.6
 
 - New `#[reflectapi(hidden)]` field attribute: the field stays in the schema (marked `"hidden": true`) and remains functional at runtime (e.g. header extraction by the axum adapter), but is excluded from generated clients, documentation, and OpenAPI specs. Not allowed on unnamed (tuple) fields, since removing a positional element would shift indices and break wire compatibility.

reflectapi-demo/src/tests/serde.rs

@@ -324,6 +324,72 @@ fn test_struct_with_flatten_optional_and_required() {
     assert_snapshot!(TestStructWithFlattenOptionalAndRequired);
 }
 
+#[test]
+fn test_struct_with_option_fields_without_serde_default() {
+    // Option fields must be optional keys in generated clients regardless of
+    // `#[serde(default)]` / `skip_serializing_if`, because serde accepts a
+    // missing key for option-typed fields unconditionally (`missing_field`
+    // special-cases `deserialize_option`, and `reflectapi::Option`
+    // deserializes the same way). The exception is a field with a custom
+    // serde deserializer: `missing_field` cannot route through
+    // `deserialize_with`, so a missing key is rejected and the field must
+    // stay required. A custom serializer alone does not affect key
+    // presence, so `serialize_with` fields remain optional, while `with`
+    // implies a custom deserializer and the field stays required.
+    fn deserialize_option<'de, D: serde::Deserializer<'de>>(
+        deserializer: D,
+    ) -> Result<Option<String>, D::Error> {
+        serde::Deserialize::deserialize(deserializer)
+    }
+
+    fn serialize_option<S: serde::Serializer>(
+        value: &Option<String>,
+        serializer: S,
+    ) -> Result<S::Ok, S::Error> {
+        serde::Serialize::serialize(value, serializer)
+    }
+
+    mod option_passthrough {
+        pub fn serialize<S: serde::Serializer>(
+            value: &std::option::Option<String>,
+            serializer: S,
+        ) -> Result<S::Ok, S::Error> {
+            serde::Serialize::serialize(value, serializer)
+        }
+
+        pub fn deserialize<'de, D: serde::Deserializer<'de>>(
+            deserializer: D,
+        ) -> Result<std::option::Option<String>, D::Error> {
+            serde::Deserialize::deserialize(deserializer)
+        }
+    }
+
+    #[allow(dead_code)]
+    #[derive(serde::Serialize, serde::Deserialize, reflectapi::Input, reflectapi::Output)]
+    #[serde(deny_unknown_fields)]
+    pub struct ARequest {
+        pub reflect_option: reflectapi::Option<String>,
+
+        #[serde(default, skip_serializing_if = "reflectapi::Option::is_undefined")]
+        pub annotated_reflect_option: reflectapi::Option<String>,
+
+        pub std_option: Option<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        pub annotated_std_option: Option<String>,
+
+        #[serde(deserialize_with = "deserialize_option")]
+        pub custom_deserializer_option: Option<String>,
+
+        #[serde(serialize_with = "serialize_option")]
+        pub custom_serializer_option: Option<String>,
+
+        #[serde(with = "option_passthrough")]
+        pub with_module_option: Option<String>,
+    }
+
+    assert_snapshot!(ARequest);
+}
+
 #[derive(reflectapi::Input, reflectapi::Output, serde::Deserialize, serde::Serialize)]
 #[serde(rename = "struct-name&&")]
 struct TestStructWithRenameToInvalidChars {