Opt-in schema evolution: #[msgpack(default)] and #[msgpack(allow_unknown_fields)]

README.md

@@ -150,6 +150,57 @@ struct Foo<'a> {
 }
 ```
 
+### default
+
+Marks a field as recoverable when its key is missing from the wire payload. On read, a missing key is filled with `Default::default()`, or with the result of a named function if `default = "path"` is supplied. Only supported on `#[msgpack(map)]` structs — array representation has no field names, so missing values cannot be detected safely.
+
+```rust
+fn default_age() -> u32 { 18 }
+
+#[derive(FromMessagePack, ToMessagePack)]
+#[msgpack(map)]
+pub struct Person {
+    pub name: String,
+
+    #[msgpack(default)]
+    pub nickname: Option<String>,
+
+    #[msgpack(default = "default_age")]
+    pub age: u32,
+}
+```
+
+`default` only controls missing keys. Unknown keys still cause a decode error unless `allow_unknown_fields` is also set on the struct.
+
+### allow_unknown_fields
+
+Struct-level opt-in that tells the decoder to skip keys it does not recognize instead of erroring. Only meaningful on `#[msgpack(map)]` structs.
+
+```rust
+#[derive(FromMessagePack, ToMessagePack)]
+#[msgpack(map, allow_unknown_fields)]
+pub struct Person {
+    pub name: String,
+    pub age: u32,
+}
+```
+
+`default` and `allow_unknown_fields` are orthogonal. Combine them for full forward/backward compatibility:
+
+```rust
+#[derive(FromMessagePack, ToMessagePack)]
+#[msgpack(map, allow_unknown_fields)]
+pub struct Person {
+    pub name: String,
+
+    #[msgpack(default)]
+    pub age: u32,
+}
+```
+
+> [!NOTE]
+> Both attributes are opt-in. Structs that use neither preserve zerompk's strict-by-default decoding behavior with byte-identical codegen.
+
 ## Design Philosophy
 
 The most popular MessagePack serializer, [rmp](https://github.com/3Hren/msgpack-rust), is highly optimized, but zerompk is designed with an even greater focus on performance.
@@ -552,7 +603,9 @@ Many of these optimizations are inspired by the high-performance MessagePack ser
 
 ## Security
 
-zerompk always requires strict type schemas for serialization/deserialization, making it almost safe against untrusted binaries. Additionally, zerompk implements measures against the following attacks:
+By default, zerompk requires strict type schemas for serialization/deserialization (every declared field must appear; no unknown keys are tolerated), making it almost safe against untrusted binaries. Schema evolution is opt-in per struct via `#[msgpack(default)]` and `#[msgpack(allow_unknown_fields)]`; structs that opt in relax these checks intentionally and should be paired with application-level validation when the input is untrusted.
+
+Additionally, zerompk implements measures against the following attacks:
 
 - Stack overflow caused by excessive object nesting. zerompk rejects objects nested beyond `MAX_DEPTH = 500` and returns an error.
 - Memory consumption due to large size headers. zerompk validates header sizes before memory allocation and returns an error if the buffer is insufficient.

README_JA.md

@@ -150,6 +150,59 @@ struct Foo<'a> {
 }
 ```
 
+### default
+
+デシリアライズにキーが存在しない場合に、そのフィールドをデフォルト値で置き換えます。欠損したキーは `Default::default()` で埋められるか、`default = "path"` が指定されている場合は名前付き関数の結果で埋められます。
+
+これは`#[msgpack(map)]` でのみサポートされています。(配列にはフィールド名がないため、欠落した値を安全に検出できません)
+
+```rust
+fn default_age() -> u32 { 18 }
+
+#[derive(FromMessagePack, ToMessagePack)]
+#[msgpack(map)]
+pub struct Person {
+    pub name: String,
+
+    #[msgpack(default)]
+    pub nickname: Option<String>,
+
+    #[msgpack(default = "default_age")]
+    pub age: u32,
+}
+```
+
+`default` は欠損したキーのみに対応します。`allow_unknown_fields` が設定されていない限り、不明なキーが含まれる場合はエラーとなります。
+
+### allow_unknown_fields
+
+デシリアライズ時に不明なキーがあった場合、エラーにする代わりにスキップするように変更します。これは`#[msgpack(map)]`でのみ有効です。
+
+```rust
+#[derive(FromMessagePack, ToMessagePack)]
+#[msgpack(map, allow_unknown_fields)]
+pub struct Person {
+    pub name: String,
+    pub age: u32,
+}
+```
+
+完全な前方互換性と後方互換性を確保するには、`default`と`allow_unknown_fields`を組み合わせて使用します。
+
+```rust
+#[derive(FromMessagePack, ToMessagePack)]
+#[msgpack(map, allow_unknown_fields)]
+pub struct Person {
+    pub name: String,
+
+    #[msgpack(default)]
+    pub age: u32,
+}
+```
+
+> [!NOTE]
+> これらの属性はオプトインです。デフォルトではzerompkは厳密なスキーマの一致を要求します。
+
 ## 設計哲学
 
 最もメジャーなMessagePackシリアライザである[rmp](https://github.com/3Hren/msgpack-rust)は十分に最適化されていますが、zerompkはそれ以上にパフォーマンスに注力した設計になっています。
@@ -561,4 +614,4 @@ zerompkはシリアライズ/デシリアライズに対して常に厳格な型
 
 ## ライセンス
 
-このライブラリは[MIT License](LICENSE)の下で公開されています。
+このライブラリは[MIT License](LICENSE)の下で公開されています。