<labelid="sidebar-toggle"class="icon-button"for="sidebar-toggle-anchor"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<ahref="../../print.html"title="Print this book"aria-label="Print this book">
<iid="print-button"class="fa fa-print"></i>
</a>
</div>
</div>
<divid="search-wrapper"class="hidden">
<formid="searchbar-outer"class="searchbar-outer">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p><ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL objects</a> represent a list of named fields, each of which yield a value of a specific type.</p>
</blockquote>
<p>When declaring a <ahref="https://graphql.org/learn/schema">GraphQL schema</a>, most of the time we deal with <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL objects</a>, because they are the only place where we actually define the behavior once <ahref="https://graphql.org/learn/schema">schema</a> gets <ahref="https://spec.graphql.org/October2021#sec-Execution">executed</a>.</p>
<p>There are two ways to define a <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> in <ahref="https://docs.rs/juniper">Juniper</a>:</p>
<li>The easiest way, suitable for trivial cases, is to use the <ahref="https://docs.rs/juniper/0.16.0/juniper/derive.GraphQLObject.html"><code>#[derive(GraphQLObject)]</code> attribute</a> on a <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a>, as described below.</li>
<li>The other way, using the <ahref="https://docs.rs/juniper/0.16.0/juniper/attr.graphql_object.html"><code>#[graphql_object]</code> attribute</a>, is described in the <ahref="complex_fields.html">"Complex fields" chapter</a>.</li>
<p>While any type in <ahref="https://www.rust-lang.org">Rust</a> can be exposed as a <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a>, the most common one is a <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a>:</p>
<p>This creates a <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> type called <code>Person</code>, with two fields: <code>name</code> of type <code>String!</code>, and <code>age</code> of type <code>Int!</code>. Because of <ahref="https://www.rust-lang.org">Rust</a>'s type system, everything is exported as <ahref="https://spec.graphql.org/October2021#sec-Non-Null">non-<code>null</code></a> by default.</p>
<p><strong>TIP</strong>: If a <code>null</code>able field is required, the most obvious way is to use <code>Option</code>. Or <ahref="https://docs.rs/juniper/0.16.0/juniper/enum.Nullable.html"><code>Nullable</code></a> for distinguishing between <ahref="https://spec.graphql.org/October2021#sel-EAFdRDHAAEJDAoBxzT">explicit and implicit <code>null</code>s</a>.</p>
<p>We should take advantage of the fact that <ahref="https://graphql.org">GraphQL</a> is <ahref="https://spec.graphql.org/October2021#sec-Introspection">self-documenting</a> and add descriptions to the defined <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> type and its fields. <ahref="https://docs.rs/juniper">Juniper</a> will automatically use associated <ahref="https://doc.rust-lang.org/reference/comments.html#doc-comments">Rust doc comments</a> as <ahref="https://spec.graphql.org/October2021#sec-Descriptions">GraphQL descriptions</a>:</p>
<p>If using <ahref="https://doc.rust-lang.org/reference/comments.html#doc-comments">Rust doc comments</a> is not desired (for example, when we want to keep <ahref="https://www.rust-lang.org">Rust</a> API docs and GraphQL schema descriptions different), the <code>#[graphql(description = "...")]</code> attribute can be used instead, which takes precedence over <ahref="https://doc.rust-lang.org/reference/comments.html#doc-comments">Rust doc comments</a>:</p>
<p>By default, <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a> fields are converted from <ahref="https://www.rust-lang.org">Rust</a>'s standard <code>snake_case</code> naming convention into <ahref="https://graphql.org">GraphQL</a>'s <code>camelCase</code> convention:</p>
<p>To <ahref="https://spec.graphql.org/October2021#sec--deprecated">deprecate</a> a <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> field, either the <code>#[graphql(deprecated = "...")]</code> attribute, or <ahref="https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute">Rust's <code>#[deprecated]</code> attribute</a>, should be used:</p>
<p><strong>NOTE</strong>: Only <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a>/<ahref="https://spec.graphql.org/October2021#sec-Interfaces">interface</a> fields and <ahref="https://spec.graphql.org/October2021#sec-Enums">GraphQL enum</a> values can be <ahref="https://spec.graphql.org/October2021#sec--deprecated">deprecated</a>.</p>
<p>By default, all <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a> fields are included into the generated <ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> type. To prevent inclusion of a specific field annotate it with the <code>#[graphql(ignore)]</code> attribute:</p>
<p><strong>TIP</strong>: See more available features in the API docs of the <ahref="https://docs.rs/juniper/0.16.0/juniper/derive.GraphQLObject.html"><code>#[derive(GraphQLObject)]</code></a> attribute.</p>
<p><ahref="https://spec.graphql.org/October2021#sec-Objects">GraphQL object</a> fields can be of any <ahref="https://graphql.org">GraphQL</a> type, except <ahref="https://spec.graphql.org/October2021#sec-Input-Objects">input objects</a>.</p>
<p>Let's see what it means to build relationships between <ahref="https://spec.graphql.org/October2021#sec-Objects">objects</a>:</p>
<p>Because <code>Person</code> is a valid <ahref="https://graphql.org">GraphQL</a> type, we can have a <code>Vec<Person></code> in a <ahref="https://doc.rust-lang.org/reference/items/structs.html">struct</a>, and it'll be automatically converted into a <ahref="https://spec.graphql.org/October2021#sec-List">list</a> of <ahref="https://spec.graphql.org/October2021#sec-Non-Null">non-<code>null</code>able</a><code>Person</code><ahref="https://spec.graphql.org/October2021#sec-Objects">objects</a>.</p>