Describing layer attributes with field descriptions (March 2019)

Much of the work you do when making a map involves working with layer attributes. Whether you’re drawing the layer, configuring a popup, or performing analysis, you need some level of knowledge of the layer’s fields and the values they contain. If it’s your own layer, you know and understand its attributes. But if it isn’t, how do you gain that knowledge? Likely, you inspect the field names and examine field values for some clues. And if you’re lucky, you’ll find some documentation that describes the layer’s attributes.

Now, with the March 2019 update of ArcGIS Online, understanding fields and their values just got easier. Whether you need to provide a detailed description of your own layer attributes or you’re using someone else’s layers, you’ll want to utilize the new field description available with hosted feature layers. Specifically, there are two new field properties that describe the values contained in a field.

• Field description –  a few words, a sentence, or a paragraph of text that describes the values in the field. The description can be up to 500 characters.
• Field value type – a keyword that categorizes the type of values contained in the field. The keyword helps people understand how to use the values and allows ArcGIS Online to make smarter suggestions for working with them.

Where do you see field descriptions?

The most prominent display of field descriptions is on the item details page of the layer, on the Data tab. When looking at the attribute table, moving the mouse over a field header will display the field name and description.

In Fields view, you’ll find a new ‘List’ option that shows field descriptions and field value types for all fields. List view makes it easier understand what attributes the layer contains. Table view is still the default view for your layers, but list view is now the default view for layers shared by others.

To help you pick the right field for drawing, you can access the field description right from the Change Style panel within the map viewer.  Keep this in mind when authoring your own field descriptions, as a meaningful tip about the attribute values can help others draw your layer effectively.

How do you set field descriptions?

When viewing fields on the data tab, click on a field name to reveal its properties. Here’s where you can configure the new description and field value type.

Why should you set the field value type?

You might ask why you need set the field value type when the field description can be quite informative. While the field description allows you to describe fields to other people, the field value type—while also helpful to people—allows you to describe your fields to ArcGIS Online and other client applications. The field value type helps these applications make better suggestions on how to work with the attributes—for instance, making Smart Mapping smarter. When provided, ArcGIS Online will leverage the field value type in specific instances, like when suggesting options for layer drawing and popup configuration. Currently, only ArcGIS Online uses the field value type, although over time other clients will start using it as appropriate.

To set a field value type, select the keyword that best categorizes the field values. Rather than presenting you with the complete list of field value type keywords up front, here’s an example to help you understand the purpose of them. Suppose you have a parcel layer that has these fields:

• Parcel ID – Integer
• Owner – string
• Street Address – String
• Property Description – String
• Buildings – Integer
• Land Area – Double
• Assessed Value – Double
• Assessment Date – Date

If you were to describe these field values, you might write something like this:

• Parcel ID – the unique identifier of the parcel
• Owner – the name of the property owner
• Street Address – the location of the parcel
• Property Description – the legal description of the property
• Buildings – the number of buildings on the parcel
• Land Area – the size of the parcel in acres
• Assessed value – the value of the parcel and buildings in dollars
• Assessment Date – the date of the last assessment

In looking at these descriptions, some words stand out, like: identifier, name, location, description, number of, size, value, and date. These are the key words that describe what the field values are. The field value type keywords are constructed from these types of words. They are:

• Name or Title
• Description
• Type or Category
• Count or Amount
• Percentage or Ratio
• Measurement
• Unique Identifier
• Ordered or Ranked
• Binary
• Location or Place Name
• Coordinate
• Date and Time

In the parcel layer example above, the Parcel ID field is an integer field. If the field value type indicates the field values represent a unique identifier rather than a count, Smart Mapping would not suggest drawing this field attribute using graduated colors or symbols. For more information, here’s a help topic that further describes field value types.

Where is the field description stored?

Field description and field value type are stored with the hosted feature layer and are accessible via the layer’s REST endpoint. If you’re an application developer who needs to access this information, you’ll find there are two new parameters: supportsFieldDescriptionProperty and description on the field itself. Note that description contains both the field description and field value type. Here’s an excerpt from the layer’s JSON that shows these parameters.

supportsFieldDescriptionProperty: true,
{
   name: "STATEFP10",
   type: "esriFieldTypeString",
   actualType: "nvarchar",
   alias: "State Code",
   sqlType: "sqlTypeNVarchar",
   length: 80,
   nullable: true,
   editable: true,
   domain: null,
   defaultValue: null,
   description: "{"value":"State FIPS code. Federal Information 
    Processing Standards (FIPS) are numeric codes assigned by the 
    National Institute of Standards and Technology (NIST). FIPS 
    codes identify US states by a 2-digit number, and US counties 
    by a 3-digit number.","fieldValueType":"typeOrCategory"}"
},

While the field value types get translated into various languages in ArcGIS Online, the strings stored at the service are essentially the English version:

• nameOrTitle
• description
• typeOrCategory
• countOrAmount
• percentageOrRatio
• measurement
• uniqueIdentifier
• orderedOrRanked
• binary
• locationOrPlaceName
• coordinate
• dateAndTime

More to come

Hopefully, you’ll find field descriptions useful. There’s still some work to do here, as we’d like to consider storing field units and formatting. We’d also like to explore extracting field descriptions from traditional metadata, where available. Let us know what you think.