ArcGIS Living Atlas

High-Quality Field Descriptions Make Mapping Easier

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:

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:

The "i" information button next to the field "Total group quarters population" in the Styles Options reveals the Field Description: 'Group quarters are defined as places where people live or stay in a group living arrangement that is owned or managed by an organization providing housing and/or services for the residents'

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.

Field description of the attribute called Division: 'A grouping of states within a census geographic region, established by the Census Bureau for the presentation of census data. 0 Not in a division (Puerto Rico), 1 New England, 2 Middle Atlantic, 3 East North Central, 4 West North Central, 5 South Atlantic, 6 East South Central, 7 West South Central, 8 Mountain, 9 Pacific'

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 "..." more options next the field called "Percent of adults who are lesbian, gay, bisexual, or transgender (LGBT)" reveals more information such as the field name (Pct_LGBTQ_Y), and a description: 'Percent of adults (18+_ who report a sexual orientation of gay, lesbian, or bisexual; or currently identified as transgender; or reported a sex assigned at birth that does not align with their current gender. Percent calculations do not use those who did not report either a gender or sexual orientation in either the numerator or the denominator, consistent with the methodology used by the source. Esri calculated field: round(LGBTQ_Y / (Total - Gender_DNR - SexOrDNR) *100, .1)'

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.

From the Data Table in the Item Page, hovering over the field "% Low birthweight" exposes a long description: '% of live births with low birthweight (less than 2,500 grams). Weight into Health Outcomes Ranking: 20%. Source: National Center for Health Statistics - Natality files. Year(s): 2014-2020.

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.

From the Item Page, Data -> Fields -> List exposes all fields in the feature layer, and their associated descriptions are here in one place. No hovering or clicking on each and every field.

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.

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.

Data -> Fields -> List is the best place to select the field you would like to edit. This is where to add descriptions to fields manually.

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.


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

About the author

(she/her/hers) Diana loves working with data. She has 15 years experience as a practitioner of demography, sociology, economics, policy analysis, and GIS. Diana holds a BA in quantitative economics and an MA in applied demography. She is a senior GIS engineer on ArcGIS Living Atlas of the World's Policy Maps team. Diana enjoys strong coffee and clean datasets, usually simultaneously.

Inline Feedbacks
View all comments

Next Article

When are expert sources right for your story?

Read this article