Making a map is a great way to visualize quantitative data because it shows the data values in combination with location intelligence. However, making a map first requires understanding the attribute(s) being mapped. If descriptions were a few clicks away, that would significantly decrease the time involved for the map maker to gain an understanding of the attributes.

The field descriptions of feature layers in ArcGIS Online are a structured place to communicate all the details of attribute fields, including:

• Definitions
• Sources
• Vintages
• Units
• Expressions for calculated fields

These descriptions help analysts navigate the ever-growing corpus of data out there by putting this field-specific documentation as close to the field as possible, limiting the amount of time analysts need to search for documentation. This way, analysts use this information to ensure they’re using the right attributes for their purposes. Many layers in ArcGIS Living Atlas include long field descriptions, including the American Community Survey hosted feature layers, 2020 Census restricting layers, the BLS unemployment layer, County Health Rankings, Justice40, and more.

Learn definitions

As GIS analysts, we know that GIS can help shed light on complex topics like climate change, social justice, and economic development by visualizing opportunities to intervene. Those complex topics often come with a specific vocabulary that allows subject matter experts to describe details efficiently. Unfortunately, to the layperson, this language can sound like industry jargon. One example of this jargon is the phrase “group quarters population” – defined as people living in group-based settings such as college dorms, military barracks, correctional facilities, or assisted living homes.

Here, I have the USA Census 2020 Redistricting Tracts layer in Map Viewer, and I see a field displayed as “Total group quarters population” in the fields list for styling the map. The “i” information button provides the definition:

Another useful type of definition included in field descriptions when appropriate are definitions for coded values. For example, every census block, block group, tract, and county are contained in a state (or state-equivalent if in Washington, DC or Puerto Rico). This state is a field on the layers for lower levels of geography. Similarly, they are also contained within a census division. The coded values for the attribute “Division” range from 0 to 9. Here, the description serves as a codebook, exposing what division each of those values correspond to.

One click on the “i” information button gives a better understanding of these topics. Not leaving the Map Viewer to get the definitions on another website saves time. The layer provided the definitions I needed in the descriptions.

Learn expressions for calculated fields

Working with calculated fields can be cumbersome and time consuming, because at times, my own calculations don’t match what I’m seeing on the layer I’m working with. I want to see the formulas used, since knowing exactly how a field was calculated can be extremely helpful. For example, this layer of Gender Identity and Sexual Orientation does not include those who did not report certain characteristics in either the numerator or denominator of percent calculations. Just as you can explore these field descriptions by clicking on the “i” information button in the Style Options, you can also do this by clicking the “…” (more options) -> “i” button on a specific field in the attribute table.

The the formula used for this field is right here for me to view. I now have greater trust in this attribute than when I wasn’t replicating the values. Again, I did not need to leave the Map Viewer and read through a methodology document from the source. My question was answered in a few clicks.

Learn sources, vintages, and units

Some datasets are so valuable in part because they bring together information from multiple sources. While it is very useful to have different types of information in one unified layer, it can raise questions about sources and vintages. However, the field description is an ideal place to store this type of attribute-specific metadata. For example, the County Health Rankings project by the Robert Wood Johnson Foundation takes on a herculean effort every year in combining several sources and updating each with the latest vintage available. This results in a very informative layer that provides attributes on topics such as obesity, smoking, child poverty, mammogram screening, and more.

Since I’m interested in underlying sources and vintages, I’m probably looking at the layer’s item page. However, much of this information is different depending on the attribute. To find out the underlying source and the vintage of the attribute I’m interested in, all I must do is click on the Data Tab from the Item Page. This brings me to the attribute tables, and from there, hover over the field I want to learn more about, in this case, percent low birthweight.

Hovering over the column exposes the field description. The source here is the National Center for Health Statistics – Natality files, for years 2014-2020. Additionally, we learn that low birthweight is defined as weight less than 2,500 grams, and that it’s 20 percent of the Health Outcomes ranking.

For large GIS projects, there are dozens of fields that have detailed information associated with them. Here the Fields List can be extremely helpful. In the Data tab, simply switch from Table view to Fields view. Try the List option or the Table option to discover what one works best for your needs. I find the List option is the most ideal because it displays all field information (including field descriptions!) in one place.

Field descriptions are visible in many places

From the examples above, you probably noticed that field descriptions come through in multiple corners of ArcGIS Online. Get to them within the Map Viewer’s symbology options, viewing the attribute table within Map Viewer, and in the Data tab of the Item Page. Exposing the field descriptions in multiple user experiences makes viewing the descriptions just a few clicks away from whatever you’re doing. Next time you’re working with a layer in Living Atlas and have a question about an attribute, check for a field description.

Include long field descriptions on your own feature layers

In most large organizations, the analysts who publish layers are different from the analysts who use the layers for mapping, and can be different from those creating dashboards, apps, and stories. Are you publishing feature layers for your organization that others use downstream in a workflow? Consider including long field descriptions on some of your layers in this case. From an organizational perspective, analysts are creating a high-quality institutional asset that can avoid misinterpretation of data, which reduces costs. From an individual perspective, analysts are providing answers to specific questions about various fields in a self-service style, reducing questions piling up in your inbox!

Creating the descriptions

The most time-intensive part of creating descriptions for fields will be writing out the descriptions themselves, since that involves looking through codebooks, metadata in data warehouses, information across multiple sources, and other kinds of technical documentation that may or may not be organized well. Since the main goal of field descriptions is to communicate information about the field, it can be worthwhile to ask people who use the map layers you create what they need to know about the attributes.

• Is the source the most important thing to put first?
• What definitions are needed?
• Do we include formulas?
• Do any acronyms need to be spelled out?

In writing descriptions for a handful of fields, analysts will quickly realize that it takes dedicated time. If creating field descriptions for every single field seems overwhelming, start with the fields that generate the most questions. What are the attributes that have the most confusion surrounding them?

The actual mechanics of applying the field descriptions are easy for the item’s owner. It can be done manually through ArcGIS Online’s graphical user interface (GUI), or through a scripted process. A scripted process is most ideal for large amounts of fields.

Applying descriptions manually through the GUI

From the Item Page, click Data -> Fields -> change from Table view to List view. Then click on any field you’d like to edit.

If you’re working with multi-scale layers, make sure the desired layer is selected in the dropdown option. If your layer contains a large number of fields, use the search bar to search within your fields. Or, use the filter options to filter by field type. The character limit for adding descriptions manually through the user interface is 500.

Applying descriptions through a scripted process

If you’d prefer a scripted process to save time and reduce potential for human error, I highly recommend Lisa Berry’s “AliasUpdater” Python script, designed to help you update the aliases and descriptions for hosted feature services. You’ll need an Excel table containing the field names, desired aliases, and desired descriptions. This script also allows for assigning other options including attribute field type, decimal places to display, and comma separators. The character limit for adding descriptions through a scripted process is 1064.

Recap

Field descriptions help clarify confusion around definitions, units, sources, vintages, and more. Many layers in Living Atlas contain field descriptions for all attributes. This helps analysts learn more about what exactly they are mapping in just a few clicks. What’s more, adding field descriptions to your own layers is straightforward.

Have you ever worked with Living Atlas layer that had a field description that cleared things up for you? Have you added field descriptions to a layer you created? Let us know in Esri Community, or in the comments below.

Photo by Dulcey Lima on Unsplash