attr-flatten.html


<!DOCTYPE HTML>
<html lang="en" >
    <head>
        <meta charset="UTF-8">
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <title>Struct flattening · Serde</title>
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="description" content="">
        <meta name="generator" content="GitBook 3.2.3">
        
        
    <link rel="stylesheet" href="gitbook/style.css">

    
                <link rel="stylesheet" href="gitbook/gitbook-plugin-codeblock-rust/block.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-checklist/checklist.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-anchors/plugin.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
                
            
        <link rel="stylesheet" href="styles/website.css">
        
    
    <meta name="HandheldFriendly" content="true"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black">
    <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
    <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">

    
    <link rel="next" href="attr-bound.html" />
    
    
    <link rel="prev" href="attr-default.html" />
    

    </head>
    <body>
        
<div class="book with-summary font-size-2">
    <div class="book-summary">
        
            
                <nav role="navigation">
                

<ul class="summary">
    
    
        <li class="chapter " data-level="1.1" data-path="./">
            
                <a href="./">
            
                    
                    Overview
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.2" data-path="help.html">
            
                <a href="help.html">
            
                    
                    Help
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.3" data-path="data-model.html">
            
                <a href="data-model.html">
            
                    
                    Serde data model
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.4" data-path="derive.html">
            
                <a href="derive.html">
            
                    
                    Using derive
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5" data-path="attributes.html">
            
                <a href="attributes.html">
            
                    
                    Attributes
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.5.1" data-path="container-attrs.html">
            
                <a href="container-attrs.html">
            
                    
                    Container attributes
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5.2" data-path="variant-attrs.html">
            
                <a href="variant-attrs.html">
            
                    
                    Variant attributes
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5.3" data-path="field-attrs.html">
            
                <a href="field-attrs.html">
            
                    
                    Field attributes
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.6" data-path="custom-serialization.html">
            
                <a href="custom-serialization.html">
            
                    
                    Custom serialization
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.6.1" data-path="impl-serialize.html">
            
                <a href="impl-serialize.html">
            
                    
                    Implementing Serialize
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.2" data-path="impl-deserialize.html">
            
                <a href="impl-deserialize.html">
            
                    
                    Implementing Deserialize
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.3" data-path="unit-testing.html">
            
                <a href="unit-testing.html">
            
                    
                    Unit testing
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7" data-path="data-format.html">
            
                <a href="data-format.html">
            
                    
                    Writing a data format
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.1" data-path="conventions.html">
            
                <a href="conventions.html">
            
                    
                    Conventions
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.2" data-path="error-handling.html">
            
                <a href="error-handling.html">
            
                    
                    Error handling
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.3" data-path="impl-serializer.html">
            
                <a href="impl-serializer.html">
            
                    
                    Implementing a Serializer
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.4" data-path="impl-deserializer.html">
            
                <a href="impl-deserializer.html">
            
                    
                    Implementing a Deserializer
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.8" data-path="lifetimes.html">
            
                <a href="lifetimes.html">
            
                    
                    Deserializer lifetimes
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9" data-path="examples.html">
            
                <a href="examples.html">
            
                    
                    Examples
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.9.1" data-path="json.html">
            
                <a href="json.html">
            
                    
                    Structs and enums in JSON
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.2" data-path="enum-representations.html">
            
                <a href="enum-representations.html">
            
                    
                    Enum representations
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.3" data-path="attr-default.html">
            
                <a href="attr-default.html">
            
                    
                    Default value for a field
            
                </a>
            

        </li>
    
        <li class="chapter active" data-level="1.9.4" data-path="attr-flatten.html">
            
                <a href="attr-flatten.html">
            
                    
                    Struct flattening
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.5" data-path="attr-bound.html">
            
                <a href="attr-bound.html">
            
                    
                    Handwritten generic type bounds
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.6" data-path="deserialize-map.html">
            
                <a href="deserialize-map.html">
            
                    
                    Deserialize for custom map type
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.7" data-path="stream-array.html">
            
                <a href="stream-array.html">
            
                    
                    Array of values without buffering
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.8" data-path="enum-number.html">
            
                <a href="enum-number.html">
            
                    
                    Serialize enum as number
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.9" data-path="attr-rename.html">
            
                <a href="attr-rename.html">
            
                    
                    Serialize fields as camelCase
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.10" data-path="attr-skip-serializing.html">
            
                <a href="attr-skip-serializing.html">
            
                    
                    Skip serializing field
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.11" data-path="remote-derive.html">
            
                <a href="remote-derive.html">
            
                    
                    Derive for remote crate
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.12" data-path="deserialize-struct.html">
            
                <a href="deserialize-struct.html">
            
                    
                    Manually deserialize struct
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.13" data-path="ignored-any.html">
            
                <a href="ignored-any.html">
            
                    
                    Discarding data
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.14" data-path="transcode.html">
            
                <a href="transcode.html">
            
                    
                    Transcode into another format
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.15" data-path="string-or-struct.html">
            
                <a href="string-or-struct.html">
            
                    
                    Either string or struct
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.16" data-path="convert-error.html">
            
                <a href="convert-error.html">
            
                    
                    Convert error types
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.17" data-path="custom-date-format.html">
            
                <a href="custom-date-format.html">
            
                    
                    Custom date format
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.10" data-path="no-std.html">
            
                <a href="no-std.html">
            
                    
                    No-std support
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.11" data-path="feature-flags.html">
            
                <a href="feature-flags.html">
            
                    
                    Feature flags
            
                </a>
            

        </li>
    

</ul>


                </nav>
            
        
    </div>

    <div class="book-body">
        
            <div class="body-inner">
                
                    
<div class="book-header" role="navigation">
    

    <!-- Title -->
    <h1>
        <i class="fa fa-circle-o-notch fa-spin"></i>
        <a href="." >Struct flattening</a>
    </h1>
</div>


                    <div class="page-wrapper" tabindex="-1" role="main">
                        <div class="page-inner">
                            
                                <section class="normal markdown-section">
                                
                                <h1 id="struct-flattening"><a name="struct-flattening" class="plugin-anchor" href="#struct-flattening"><i class="fa fa-link" aria-hidden="true"></i></a>Struct flattening</h1>
<p>The <code>flatten</code> attribute inlines keys from a field into the parent struct.
<code>flatten</code> may be used any number of times within the same struct. It is
supported only within structs that have named fields, and the field to which it
is applied must be a struct or map type.</p>
<p><em>Note:</em> <code>flatten</code> is not supported in combination with structs that use
<a href="container-attrs.html#deny_unknown_fields"><code>deny_unknown_fields</code></a>. Neither the outer nor inner flattened struct should use
that attribute.</p>
<p>The <code>flatten</code> attribute serves the following two common use cases:</p>
<h3 id="factor-out-frequently-grouped-keys"><a name="factor-out-frequently-grouped-keys" class="plugin-anchor" href="#factor-out-frequently-grouped-keys"><i class="fa fa-link" aria-hidden="true"></i></a>Factor out frequently grouped keys</h3>
<p>Consider a paginated API which returns a page of results along with pagination
metadata that identifies how many results were requested, how far into the total
set of results we are looking at, and how many results exist in total. If we are
paging through a total of 1053 results 100 at a time, the third page may look
like this.</p>
<pre><code class="lang-json">{
  <span class="hljs-string">&quot;limit&quot;</span>: <span class="hljs-number">100</span>,
  <span class="hljs-string">&quot;offset&quot;</span>: <span class="hljs-number">200</span>,
  <span class="hljs-string">&quot;total&quot;</span>: <span class="hljs-number">1053</span>,
  <span class="hljs-string">&quot;users&quot;</span>: [
    {<span class="hljs-string">&quot;id&quot;</span>: <span class="hljs-string">&quot;49824073-979f-4814-be10-5ea416ee1c2f&quot;</span>, <span class="hljs-string">&quot;username&quot;</span>: <span class="hljs-string">&quot;john_doe&quot;</span>},
    ...
  ]
}
</code></pre>
<p>This same scheme with <code>&quot;limit&quot;</code> and <code>&quot;offset&quot;</code> and <code>&quot;total&quot;</code> fields may be
shared across lots of different API queries. For example we may want paginated
results when querying for users, for issues, for projects, etc.</p>
<p>In this case it can be convenient to factor the common pagination metadata fields
into a shared struct that can be flattened into each API response object.</p>
<pre><code class="lang-rust"><span class="hljs-meta">#[derive(Serialize, Deserialize)]</span>
<span class="hljs-class"><span class="hljs-keyword">struct</span> <span class="hljs-title">Pagination</span></span> {
    limit: <span class="hljs-keyword">u64</span>,
    offset: <span class="hljs-keyword">u64</span>,
    total: <span class="hljs-keyword">u64</span>,
}

<span class="hljs-meta">#[derive(Serialize, Deserialize)]</span>
<span class="hljs-class"><span class="hljs-keyword">struct</span> <span class="hljs-title">Users</span></span> {
    users: <span class="hljs-built_in">Vec</span>&lt;User&gt;,

    <span class="hljs-meta">#[serde(flatten)]</span>
    pagination: Pagination,
}
</code></pre>
<h3 id="capture-additional-fields"><a name="capture-additional-fields" class="plugin-anchor" href="#capture-additional-fields"><i class="fa fa-link" aria-hidden="true"></i></a>Capture additional fields</h3>
<p>A field of map type can be flattened to hold additional data that is not
captured by any other fields of the struct.</p>
<pre><code class="lang-rust"><span class="hljs-keyword">use</span> std::collections::HashMap;
<span class="hljs-keyword">use</span> serde::{Serialize, Deserialize};
<span class="hljs-keyword">use</span> serde_json::Value;

<span class="hljs-meta">#[derive(Serialize, Deserialize)]</span>
<span class="hljs-class"><span class="hljs-keyword">struct</span> <span class="hljs-title">User</span></span> {
    id: <span class="hljs-built_in">String</span>,
    username: <span class="hljs-built_in">String</span>,

    <span class="hljs-meta">#[serde(flatten)]</span>
    extra: HashMap&lt;<span class="hljs-built_in">String</span>, Value&gt;,
}
</code></pre>
<p>For example if we fill the flattened <code>extra</code> field with the key <code>&quot;mascot&quot;:
&quot;Ferris&quot;</code>, it would serialize to the following JSON representation.</p>
<pre><code class="lang-json">{
  <span class="hljs-string">&quot;id&quot;</span>: <span class="hljs-string">&quot;49824073-979f-4814-be10-5ea416ee1c2f&quot;</span>,
  <span class="hljs-string">&quot;username&quot;</span>: <span class="hljs-string">&quot;john_doe&quot;</span>,
  <span class="hljs-string">&quot;mascot&quot;</span>: <span class="hljs-string">&quot;Ferris&quot;</span>
}
</code></pre>
<p>Deserialization of this data would populate <code>&quot;mascot&quot;</code> back into the flattened
<code>extra</code> field. This way additional data in an object can be collected for later
processing.</p>

                                
                                </section>
                            
                        </div>
                    </div>
                
            </div>

            
                <a href="attr-default.html" class="navigation navigation-prev " aria-label="Previous page: Default value for a field">
                    <i class="fa fa-angle-left"></i>
                </a>
                
                
                <a href="attr-bound.html" class="navigation navigation-next " aria-label="Next page: Handwritten generic type bounds">
                    <i class="fa fa-angle-right"></i>
                </a>
                
            
    </div>

    <script>
        var gitbook = gitbook || [];
        gitbook.push(function() {
            gitbook.page.hasChanged({"page":{"title":"Struct flattening","level":"1.9.4","depth":2,"next":{"title":"Handwritten generic type bounds","level":"1.9.5","depth":2,"path":"attr-bound.md","ref":"attr-bound.md","articles":[]},"previous":{"title":"Default value for a field","level":"1.9.3","depth":2,"path":"attr-default.md","ref":"attr-default.md","articles":[]},"dir":"ltr"},"config":{"plugins":["-search","-sharing","sane-sidebar","codeblock-omit","codeblock-rust","edit-link","ga4","bulk-redirect","checklist","anchors"],"root":"_src","styles":{"pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css","website":"styles/website.css"},"pluginsConfig":{"checklist":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"codeblock-rust":{},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"sane-sidebar":{},"codeblock-omit":{},"bulk-redirect":{"redirectsFile":"redirects.json"},"ga4":{"anonymize_ip":true,"cookie_domain":"serde.rs","tag":"G-T5QD1R7FZW"},"edit-link":{"label":"Edit","base":"https://github.com/serde-rs/serde-rs.github.io/edit/master/_src"},"theme-default":{"styles":{"pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css","website":"styles/website.css"},"showLevel":false},"anchors":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Serde","language":"en","gitbook":"*"},"file":{"path":"attr-flatten.md","mtime":"2022-07-28T19:54:28.669Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2025-04-13T15:56:48.597Z"},"basePath":".","book":{"language":""}});
        });
    </script>
</div>

        
    <script src="gitbook/gitbook.js"></script>
    <script src="gitbook/theme.js"></script>
    
        
        <script src="gitbook/gitbook-plugin-sane-sidebar/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-edit-link/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-ga4/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
        
    
    </body>
</html>