---
title: "Deserialize YAML tags into Rust enums"
url: https://recursiveai.org/oneyaml/rust/cookbook/deserialize-yaml-tagged-enums/
description: "Read !Point and !Rect YAML tags as Serde enum variants with sequence and mapping payloads, and see the error if the tag is unknown."
version: "1.2.0"
---

# Deserialize YAML tags into Rust enums

**oneyaml** is a free, open-source YAML library for Rust from Recursive AI. MIT or Apache-2.0, no unsafe code.

[crates.io](https://crates.io/crates/oneyaml) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-rust) · [Docs](https://recursiveai.org/oneyaml/rust/docs/) · [Download example (.zip)](https://recursiveai.org/oneyaml/rust/cookbook/deserialize-yaml-tagged-enums/deserialize-yaml-tagged-enums.zip)

A YAML tag like `!Point` selects the matching Rust variant with Serde’s `Deserialize`. No extra enum attribute is needed.

```shell
cargo add oneyaml
cargo add serde --features derive
```

```rust
#[derive(Debug, serde::Deserialize)]
enum Shape {
    Point(i32, i32),
    Rect { w: u32, h: u32 },
}
fn main() -> Result<(), oneyaml::Error> {
    let samples = [
        "!Point [3, 4]", "!Rect {w: 5, h: 6}",
    ];
    for yaml in samples {
        match oneyaml::from_str::<Shape>(yaml)? {
            Shape::Point(x, y) => {
                println!("Point: {x}, {y}");
            }
            Shape::Rect { w, h } => {
                println!("Rect: {w} × {h}");
            }
        }
    }
    Ok(())
}
```

Unzip [the example](https://recursiveai.org/oneyaml/rust/cookbook/deserialize-yaml-tagged-enums/deserialize-yaml-tagged-enums.zip), then `cargo run`.

Requires Rust 1.85 or later.

```text
Point: 3, 4
Rect: 5 × 6
```

## The full program

The full example also tries `!Hexagon [3, 4]`. An unknown tag returns a deserialization error instead of falling back to a different variant.

```rust
#[derive(Debug, serde::Deserialize)]
enum Shape {
    Point(i32, i32),
    Rect { w: u32, h: u32 },
}
fn main() -> Result<(), oneyaml::Error> {
    let samples = [
        "!Point [3, 4]", "!Rect {w: 5, h: 6}",
    ];
    for yaml in samples {
        match oneyaml::from_str::<Shape>(yaml)? {
            Shape::Point(x, y) => {
                println!("Point: {x}, {y}");
            }
            Shape::Rect { w, h } => {
                println!("Rect: {w} × {h}");
            }
        }
    }

    let err = oneyaml::from_str::<Shape>("!Hexagon [3, 4]")
        .expect_err("unknown variant");
    println!("{err}");
    Ok(())
}
```

`cargo run` prints:

```text
Point: 3, 4
Rect: 5 × 6
unknown variant `Hexagon`, expected `Point` or `Rect` (1:10)
```

## Related recipes

- [Parse YAML into Rust structs](https://recursiveai.org/oneyaml/rust/cookbook/parse-yaml-into-structs/)
- [Show YAML errors with line and column](https://recursiveai.org/oneyaml/rust/cookbook/errors-with-line-and-column/)

## The short answer

Derive `serde::Deserialize` on the enum and use `oneyaml::from_str` in Rust. The tag selects `Shape::Point`, and Serde reads the sequence `[3, 4]` as its two tuple fields. `!Rect` selects the struct variant and reads the named `w` and `h` fields from its mapping. oneyaml-rust [covers both representations at this version](https://github.com/recursive-ai-oss/oneyaml-rust/blob/14445615f5a5b2895fdaa1da7719584ef15d9d6b/crates/oneyaml/tests/serde_de.rs#L238-L253).

## How do you deserialize a tagged enum with Serde?

Pick the Rust variant shape to match the YAML that follows the tag. A tuple is suitable for a short list with a fixed order: the first coordinate in `!Point [3, 4]` is `x` and the second is `y`. For fields readers should be able to recognize by name, use a struct variant, as in `!Rect {w: 5, h: 6}`. A tag selects a variant, but it doesn’t make the payload valid. For example, a mapping is not the two-item sequence the `Point` tuple asks for.

The loader also accepts a one-entry mapping with the variant as the key. The [pinned examples](https://github.com/recursive-ai-oss/oneyaml-rust/blob/14445615f5a5b2895fdaa1da7719584ef15d9d6b/crates/oneyaml/tests/serde_de.rs#L222-L247) read `Point: [1, 2]` and `Rect: {w: 1, h: 2}` into the same enum variants as the tag forms. If you own the file format, choose one spelling for your examples so readers have a consistent pattern to copy.

## Is a YAML tag the same as `#[serde(tag = "type")]`?

No. `!Rect` is a YAML tag, outside the value’s content. Serde’s [internally tagged representation](https://serde.rs/enum-representations.html#internally-tagged) instead looks for a named field such as `type` inside the mapping. That representation doesn’t support tuple variants such as `Point(i32, i32)`. Use the default externally tagged enum when the file uses `!Variant` or a one-entry map whose key names the variant. Reach for the internally tagged representation when the format already uses a discriminator field and your enum has compatible variants.
