po4yka/rust-skills / skills/rust-serde
rust-serde
VerifiedUse when deriving or changing Serialize or Deserialize on a type whose encoded form is a contract (config, stored record, or wire message), or when serde_json drops a field, reorders keys, or loses number precision without an error. Triggers on deny_unknown_fields, rename_all, serde(alias), serde(tag), untagged, serde(flatten), skip_serializing_if, serde(default), serde(try_from), DeserializeOwned, JSON map key, large integer, preserve_order, float_roundtrip, arbitrary_precision, postcard, "unknown field", "did not match any variant".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.5 KB |
| references/data-model-and-lifetimes.md | markdown | 4.4 KB |
| references/enum-representations.md | markdown | 3.2 KB |
| references/format-crates.md | markdown | 885 B |
| references/schema-evolution.md | markdown | 3.3 KB |
| references/wire-tests.md | markdown | 1.8 KB |
references/enum-representations.md
View on GitHub# Enum representations
Read this when you choose or change the serde representation of an enum, or an enum fails
at runtime in one format. Measured with serde 1.0.229, serde_json 1.0.154, and postcard 1.1.3 on
Rust 1.99.1, and with bincode 2.0.1 on Rust 1.98.1.
Contents:
- The four representations
- `untagged` costs the error message and can pick the wrong variant
## The four representations
```rust
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
enum External { Ping, Data(u64) }
#[derive(Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum Internal { Ping, Data { size: u64 } }
#[derive(Serialize, Deserialize)]
#[serde(tag = "t", content = "c", rename_all = "snake_case")]
enum Adjacent { Ping, Data(u64) }
#[derive(Serialize, Deserialize)]
#[serde(untagged)]
enum Untagged { Number(u64), Text(String) }
```
For the `Data` variant carrying `3`:
| Representation | On the wire | Payload constraint | postcard, bincode (not self-describing) |
| --- | --- | --- | --- |
| External (default) | `{"data":3}` | None | Works |
| Internal (`tag`) | `{"type":"data","size":3}` | Struct, unit, or newtype holding a struct or map | Fails at runtime |
| Adjacent (`tag` + `content`) | `{"t":"data","c":3}` | None | Fails at runtime |
| Untagged | `3` | First variant whose shape fits wins | Fails at runtime |
Internal tagging is the usual choice for a JSON message type, because the tag reads naturally
and the payload stays flat. Adjacent tagging is the fallback when a variant holds something that
is not a map. Use external tagging when the type must also go through a binary format, or build
without serde's `alloc` feature. serde documents it as the only representation for no-alloc
builds, and the postcard and bincode results in the table show the same for those formats.
Internal tagging rejects a tuple variant at compile time. A newtype variant that holds a scalar
compiles and fails only at runtime:
```text
cannot serialize tagged newtype variant <Enum>::<Variant> containing an integer
invalid type: map, expected u64
```
The first line comes from serialization, the second from deserialization of `{"type":"data"}`.
On postcard, deserialization of the internal, adjacent, and untagged forms fails with
`This is a feature that PostCard will never implement`; bincode 2 reports `AnyNotSupported` or
`IdentifierNotSupported`. The derive compiles for all four.
## `untagged` costs the error message and can pick the wrong variant
An untagged enum tries each variant in order. When none fits, the error names no field and no
expected type:
```text
data did not match any variant of untagged enum Untagged
```
Nested in a struct, it adds only the position where the value ends (`at line 1 column N`). An
externally tagged enum at the same place names the expected type:
`invalid type: string "notnum", expected u64`.
The first variant that fits wins, even when a later one fits better. With variants
`Short { x: u8 }` and `Long { x: u8, y: u8 }` in that order, `{"x":1,"y":2}` parses as
`Short { x: 1 }` and drops `y` without an error. Put the variant with the most fields first, or
add `deny_unknown_fields` to the enum.
Do not use `untagged` for a message enum or a config section.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |