<p><strong>Structures</strong>, or <strong>structs</strong>, are used to collect multiple pieces of information together in one unit. These <ahref="https://www.digitalocean.com/community/tutorials/defining-structs-in-go">collections of information</a> are used to describe higher-level concepts, such as an <code>Address</code> composed of a <code>Street</code>, <code>City</code>, <code>State</code>, and <code>PostalCode</code>. When you read this information from systems such as databases, or APIs, you can use <strong>struct tags</strong> to control how this information is assigned to the fields of a struct. Struct tags are small pieces of metadata attached to fields of a struct that provide instructions to other Go code that works with the struct.</p>
<h2id="what-does-a-struct-tag-look-like">What Does a Struct Tag Look Like?</h2>
<p>Go struct tags are annotations that appear after the type in a Go struct declaration. Each tag is composed of short strings associated with some corresponding value. </p>
<p>A struct tag looks like this, with the tag offset with backtick <code>`</code> characters:</p>
<p>Other Go code is then capable of examining these structs and extracting the values assigned to specific keys it requests. Struct tags have no effect on the operation of your code without additional code that examines them.</p>
<p>Try this example to see what struct tags look like, and that without code from another package, they will have no effect.</p>
<spanclass="w"></span><spanclass="k">return</span><spanclass="w"></span><spanclass="nx">fmt</span><spanclass="p">.</span><spanclass="nx">Sprintf</span><spanclass="p">(</span><spanclass="s">"Hi! My name is %s"</span><spanclass="p">,</span><spanclass="w"></span><spanclass="nx">u</span><spanclass="p">.</span><spanclass="nx">Name</span><spanclass="p">)</span><spanclass="w"></span>
<spanclass="na">Hi! My name is Sammy</span><spanclass="w"></span>
</code></pre></div>
<p>This example defines a <code>User</code> type with a <code>Name</code> field. The <code>Name</code> field has been given a struct tag of <code>example:"name"</code>. We would refer to this specific tag in conversation as the “example struct tag” because it uses the word “example” as its key. The <code>example</code> struct tag has the value <code>"name"</code> for the <code>Name</code> field. On the <code>User</code> type, we also define the <code>String()</code> method required by the <code>fmt.Stringer</code> interface. This will be called automatically when we pass the type to <code>fmt.Println</code> and gives us a chance to produce a nicely formatted version of our struct.</p>
<p>Within the body of <code>main</code>, we create a new instance of our <code>User</code> type and pass it to <code>fmt.Println</code>. Even though the struct had a struct tag present, we see that it has no effect on the operation of this Go code. It will behave exactly the same if the struct tag were not present.</p>
<p>To use struct tags to accomplish something, other Go code must be written to examine structs at runtime. The standard library has packages that use struct tags as part of their operation. The most popular of these is the <code>encoding/json</code> package.</p>
<h2id="encoding-json">Encoding JSON</h2>
<p>JavaScript Object Notation (JSON) is a textual format for encoding collections of data organized under different string keys. It’s commonly used to communicate data between different programs as the format is simple enough that libraries exist to decode it in many different languages. The following is an example of JSON:</p>
<p>This JSON object contains two keys, <code>language</code> and <code>mascot</code>. Following these keys are the associated values. Here the <code>language</code> key has a value of <code>Go</code> and <code>mascot</code> is assigned the value <code>Gopher</code>.</p>
<p>The JSON encoder in the standard library makes use of struct tags as annotations indicating to the encoder how you would like to name your fields in the JSON output. These JSON encoding and decoding mechanisms can be found in the <code>encoding/json</code><ahref="https://pkg.go.dev/encoding/json">package</a>.</p>
<p>Try this example to see how JSON is encoded without struct tags:</p>
<spanclass="w"></span><spanclass="nx">Name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"Sammy the Shark"</span><spanclass="p">,</span><spanclass="w"></span>
<p>We defined a struct describing a user with fields including their name, password, and the time the user was created. Within the <code>main</code> function, we create an instance of this user by supplying values for all fields except <code>PreferredFish</code> (Sammy likes all fish). We then passed the instance of <code>User</code> to the <code>json.MarshalIndent</code> function. This is used so we can more easily see the JSON output without using an external formatting tool. This call could be replaced with <code>json.Marshal(u)</code> to print JSON without any additional whitespace. The two additional arguments to <code>json.MarshalIndent</code> control the prefix to the output (which we have omitted with the empty string), and the characters to use for indenting, which here are two space characters. Any errors produced from <code>json.MarshalIndent</code> are logged and the program terminates using <code>os.Exit(1)</code>. Finally, we cast the <code>[]byte</code> returned from <code>json.MarshalIndent</code> to a <code>string</code> and passed the resulting string to <code>fmt.Println</code> for printing on the terminal.</p>
<p>The fields of the struct appear exactly as named. This is not the typical JSON style that you may expect, though, which uses camel casing for names of fields. You’ll change the names of the field to follow camel case style in this next example. As you’ll see when you run this example, this won’t work because the desired field names conflict with Go’s rules about exported field names.</p>
<spanclass="w"></span><spanclass="nx">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"Sammy the Shark"</span><spanclass="p">,</span><spanclass="w"></span>
<p>In this version, we’ve altered the names of the fields to be camel cased. Now <code>Name</code> is <code>name</code>, <code>Password</code> is <code>password</code>, and finally <code>CreatedAt</code> is <code>createdAt</code>. Within the body of <code>main</code> we’ve changed the instantiation of our struct to use these new names. We then pass the struct to the <code>json.MarshalIndent</code> function as before. The output, this time is an empty JSON object, <code>{}</code>.</p>
<p>Camel casing fields properly requires that the first character be lower-cased. While JSON doesn’t care how you name your fields, Go does, as it indicates the visibility of the field outside of the package. Since the <code>encoding/json</code> package is a separate package from the <code>main</code> package we’re using, we must uppercase the first character in order to make it visible to <code>encoding/json</code>. It would seem that we’re at an impasse. We need some way to convey to the JSON encoder what we would like this field to be named.</p>
<h3id="using-struct-tags-to-control-encoding">Using Struct Tags to Control Encoding</h3>
<p>You can modify the previous example to have exported fields that are properly encoded with camel-cased field names by annotating each field with a struct tag. The struct tag that <code>encoding/json</code> recognizes has a key of <code>json</code> and a value that controls the output. By placing the camel-cased version of the field names as the value to the <code>json</code> key, the encoder will use that name instead. This example fixes the previous two attempts:</p>
<spanclass="w"></span><spanclass="nx">Name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"Sammy the Shark"</span><spanclass="p">,</span><spanclass="w"></span>
<p>We’ve changed the struct fields back to be visible to other packages by capitalizing the first letters of their names. However, this time we’ve added struct tags in the form of <code>json:"name"</code>, where <code>"name"</code> was the name we wanted <code>json.MarshalIndent</code> to use when printing our struct as JSON.</p>
<p>We’ve now successfully formatted our JSON correctly. Notice, however, that the fields for some values were printed even though we did not set those values. The JSON encoder can eliminate these fields as well, if you like.</p>
<p>It is common to suppress outputting fields that are unset in JSON. Since all types in Go have a “zero value,” some default value that they are set to, the <code>encoding/json</code> package needs additional information to be able to tell that some field should be considered unset when it assumes this zero value. Within the value part of any <code>json</code> struct tag, you can suffix the desired name of your field with <code>,omitempty</code> to tell the JSON encoder to suppress the output of this field when the field is set to the zero value. The following example fixes the previous examples to no longer output empty fields:</p>
<spanclass="w"></span><spanclass="nx">Name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"Sammy the Shark"</span><spanclass="p">,</span><spanclass="w"></span>
<p>We’ve modified the previous examples so that the <code>PreferredFish</code> field now has the struct tag <code>json:"preferredFish,omitempty"</code>. The presence of the <code>,omitempty</code> augmentation causes the JSON encoder to skip that field, since we decided to leave it unset. This had the value <code>null</code> in our previous examples’ outputs.</p>
<p>This output is looking much better, but we’re still printing out the user’s password. The <code>encoding/json</code> package provides another way for us to ignore private fields entirely.</p>
<p>Some fields must be exported from structs so that other packages can correctly interact with the type. However, the nature of these fields may be sensitive, so in these circumstances, we would like the JSON encoder to ignore the field entirely—even when it is set. This is done using the special value <code>-</code> as the value argument to a <code>json:</code> struct tag.</p>
<p>This example fixes the issue of exposing the user’s password.</p>
<spanclass="w"></span><spanclass="nx">Name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"Sammy the Shark"</span><spanclass="p">,</span><spanclass="w"></span>
<p>The only thing we’ve changed in this example from previous ones is that the password field now uses the special <code>"-"</code> value for its <code>json:</code> struct tag. In the output from this example that the <code>password</code> field is no longer present.</p>
<p>These features of the <code>encoding/json</code> package — <code>,omitempty</code>, <code>"-"</code>, and <ahref="https://pkg.go.dev/encoding/json#Marshal">other options</a> — are not standards. What a package decides to do with values of a struct tag depends on its implementation. Because the <code>encoding/json</code> package is part of the standard library, other packages have also implemented these features in the same way as a matter of convention. However, it’s important to read the documentation for any third-party package that uses struct tags to learn what is supported and what is not.</p>
<h2id="conclusion">Conclusion</h2>
<p>Struct tags offer a powerful means to augment the functionality of code that works with your structs. Many standard library and third-party packages offer ways to customize their operation through the use of struct tags. Using them effectively in your code provides both this customization behavior and succinctly documents how these fields are used to future developers.</p>
