How to Use schema.org Enumerations

Enumerations are a feature of schema.org that allow publishers to select a value for a property from a restricted list of values, such as the answer to a question where the only possible responses are "yes", "no" and "maybe".

Enumerations are useful both to publishers and data consumers (like search engines) because they provide unambiguous and consistently-formed information about the thing being described.

While enumerations are an important part of schema.org, the documentation describing them is rather sparse. With this article I hope to provide a bit more information about schema.org enumerations: what they are, where to find them and how to use them.

Contents

What is a schema.org enumeration?

An enumeration is a property value that comes from a limited set of possible values for that property. An enumeration is an instance of values in this set, which are collectively called enumeration members.

For example, the type:

RsvpAction

Permits the use of the property:

rsvpResponse

The expected type for this property is the enumeration:

RsvpResponseType

Which has the members:

The value for rpvpResponse should be one of these three values, because the expected type for this property is RsvpResponseType.

Using RsvpAction as an example, if the response to an RSVP was "yes", the value http://schema.org/RsvpResponseYes would be used for the property rpvpResponse.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "RsvpAction",
  "agent": {
    "@type": "Person",
    "name": "Aaron"
  },
  "event": {
    "@type": "SportsEvent",
    "name": "Stanley Cup finals"
  },
    rsvpResponse": "http://schema.org/RsvpResponseYes"
}
</script>

Further code examples can be found below.

How can I tell when an enumeration should be used?>

You can tell that an schema.org enumeration should be used when the expected type for a property is an enumeration.

How to identify when a schema.org enumeration is required

You can tell the type you're looking at is an enumeration type because it a direct child of the hierarchy Thing > Intangible > Enumeration.

Identifying a schema.org enumeration type

Where can I find the enumerations that I should use?

Enumeration members – the values that should be used when a property expects an enumeration type – can be found at the bottom of the page for that enumeration type.

A schema.org enumeration type, showing enumeration members at the bottom of the page

You can tell the type you're looking at is an enumeration member because it is a child of an enumeration type, and because it is preceded by two colons ("::").

Identifying a schema.org enumeration member

Note that enumeration types usually, but not always, include "Type" in their name. For example GameServerStatus is an enumeration type, even though its name does not include the word "Type".

schema.org enumeration types do not always include the word Type in their name

Should I use a URL or text for an enumeration value?

Either a URL or a text string can be provided as an enumeration value.

However, when the use of an enumeration member is prescribed by a search engine, and it exists as a schema.org type, the schema.org URL for that enumeration member should be used. This will help ensure that a page is eligible for any search result features, like Google rich results, that require schema.org enumerations to be used.

For example, when declaring that a product is in stock, use the value http://schema.org/InStock for the property availability.

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Product",
  "name": "Blue Widget",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "119.99",
    "availability": "http://schema.org/InStock"
  }
}
</script>

Note that Google, when parsing JSON-LD, will resolve the full URL of a valid schema.org enumeration member without it being explicitly specified as a URL.

Code:

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Product",
  "name": "Blue Widget",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "119.99",
    "availability": "InStock"
  }
}
</script>

Google Structured Data Testing Tool result:

Google Structured Data Testing Tool result for an schema.org enumeration in JSON-LD where a URL has not been used for the value

However, if a text string is provided for a property which is not a schema.org enumeration member, Google will interpret this in JSON-LD code as text.

Code:

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Product",
  "name": "Blue Widget",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "119.99",
    "availability": "InTransit"
  }
}
</script>

Google Structured Data Testing Tool result:

Google Structured Data Testing Tool result for an enumeration in JSON-LD where the enumeration is not present on schema.org

Even for valid schema.org enumerations, other data processors may not parse this JSON-LD-provided data in the same way, making it advisable to use an absolute URL whenever specifying a schema.org enumeration member as a value.

Code:

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Product",
  "name": "Blue Widget",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "119.99",
    "availability": "InStock"
  }
}
</script>

Yandex Structured Data Validator result:

Yandex Structured Data Validator result for an schema.org enumeration in JSON-LD where a URL has not been used for the value

For microdata an absolute URL should always be used, especially if the <link> element is used as its href attribute requires a URL.

Code:

<div itemscope itemtype="http://schema.org/Product">
  <span itemprop="name">Blue Widget</span>
  <span itemprop="offers" itemscope itemtype="http://schema.org/Offer">
    Price: $179.99
    <meta itemprop="priceCurrency" content="USD" />
    $<span itemprop="price">119.99</span>
    <link itemprop="availability" href="http://schema.org/InStock"/>In stock! Order now!
  </span>
</div>

Google Structured Data Testing Tool result:

Google Structured Data Testing Tool result for an schema.org enumeration in microdata where a URL has been used for the value

Failure to specify an absolute URL for the value of href results in Google minting an incorrect URL.

Code:

<div itemscope itemtype="http://schema.org/Product">
  <span itemprop="name">Blue Widget</span>
  <span itemprop="offers" itemscope itemtype="http://schema.org/Offer">
    Price: $179.99
    <meta itemprop="priceCurrency" content="USD" />
    $<span itemprop="price">119.99</span>
    <link itemprop="availability" href="InStock"/>In stock! Order now!
  </span>
</div>

Structured Data Testing Tool result:

Google Structured Data Testing Tool result for an schema.org enumeration in microdata where a URL has not been used for the value

In short, use an absolute URL for an enumeration value unless you are explicitly providing a text value (which will never the be case if you're using an valid schema.org enumeration member). URLs are also required by external enumerations, described below.

What URL do I use for an enumeration defined in a schema.org extension?

When an enumeration member is defined in an extension, use schema.org/[Type] rather than [extension].schema.org/[Type], as schema.org/[Type] is the canonical URL for that type.

For example, for the enumeration member GraphicNovel use schema.org/GraphicNovel rather than bib.schema.org/GraphicNovel.

The schema.org enumeration member GraphicNovel

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Book",
  "name": "Maus",
  "author": "Art Spiegelman",
  "bookFormat": "http://schema.org/GraphicNovel"
}
</script>

Search engine-specific enumerations

Sometimes a search engine will recommend or require use of an enumeration that does not exist in schema.org, or it may restrict the enumeration members that may be used to a subset of enumeration members available in schema.org. In these cases follow the search engine guidelines when your aim is to ensure you are eligible for features supported by that search engine.

For example, Yandex provides a list of values it supports for the property videoQuality, even though the expected type for this property in schema.org is simply text.

Values supported by Yandex for the property schema.org/videoQuality

How are schema.org enumerations used by search engines?

Search engines require enumerations whenever they want publishers to supply an unambiguous value for a property so they can provide equally unambiguous results about an entity.

For example, if a business is open from 9:00 AM to 9:00 PM on Monday, Google expects the business owner to provide the value Monday for dayOfWeek rather than, say, Mon or Lundi. This helps them accurately provide the correct opening hours for a local business in search results.

Sometimes it's clear when an enumeration value has been used to populate a portion of Google rich result, as in this product rich result for a camera.

Product rich result for a camera, showing the availability status that has been derived from an enumeration

The "In stock" annotation visible in this search snippet is probably derived from the use of the enumeration member InStock, which is present in the code of the target page.

Use of the enumeration value InStock on a product details page for a camera

What are external enumerations?

As detailed in this post, an external enumeration is one where the value is a URL from a vocabulary or data structure external to schema.org.

For example (as per the sample code for Offer), commonly-used values for the property businessFunction, which expects the enumeration BusinessFunction, are from the GoodRelations vocabulary.

<script type="application/ld+json">
{
  "@context":  "http://schema.org/",
  "@id": "#record",
  "@type": "Book",
  "additionalType": "Product",
  "name": "Le concerto",
  "author": "Ferchault, Guy",
  "offers":{
      "@type": "Offer",
      "availability": "http://schema.org/InStock",
      "serialNumber": "CONC91000937",
      "sku": "780 R2",
      "offeredBy": {
          "@type": "Library",
          "@id": "http://library.anytown.gov.uk",
          "name": "Anytown City Library"
      },
      "businessFunction": "http://purl.org/goodrelations/v1#LeaseOut",
      "itemOffered": "#record"
    }
}
</script>

schema.org enumeration examples

Out-of-stock product (JSON-LD)

Using the enumeration type ItemAvailability on property availability to indicate a product is out-of-stock.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Product",
  "name": "Blue Widget",
  "offers": {
    "@type": "Offer",
    "availability": "http://schema.org/OutOfStock",
    "price": "99.00",
    "priceCurrency": "USD"
  }
}
</script>

Confirmed flight reservation (JSON-LD)

Using the enumeration type ReservationStatusType on property reservationStatus to indicate a flight reservation has been confirmed.

script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "FlightReservation",
  "reservationId": "AXZ45M",
  "reservationStatus": "http://schema.org/ReservationConfirmed",
  "underName": {
    "@type": "Person",
    "name": "Josh Green"
  },
  "reservationFor": {
    "@type": "Flight",
    "flightNumber": "AC34",
    "provider": {
      "@type": "Airline",
      "name": "Air Canada"
    },
    "departureAirport": {
      "@type": "Airport",
      "name": "Vancouver International Airport",
      "iataCode": "YVR"
    },
    "departureTime": "2018-03-04T08:00:00-08:00",
    "arrivalAirport": {
      "@type": "Airport",
      "name": "Toronto Pearson International Airport",
      "iataCode": "YYZ"
    },
    "arrivalTime": "2017-03-04T15:23:00-05:00"
  }
}
</script>

Toll-free number (microdata)

Using the enumeration type ContactPointOption on property contactOption to indicate that a customer service telephone number is toll-free.

<div itemscope itemtype="http://schema.org/Organization">
  <span itemprop="name">The Widget Factory</span>
Call us toll-free:
  <div itemprop="contactPoint" itemscope itemtype="http://schema.org/ContactPoint">
    <span itemprop="telephone">+1-800-232-1293</span>
    <meta itemprop="contactType" content="Customer Service" />
    <link itemprop="contactOption" href="http://schema.org/TollFree" />
  </div>
 </div>

Cancelled event (RDFa)

Using the enumeration type EventStatusType on property eventStatus to indicate that an event has been cancelled.

<div vocab="http://schema.org/" typeof="Event">
  <div class="event-date" property="startDate" content="2018-09-14T09:00">Fri Sep 14</div>
  <div class="event-title" property="name">CANCELLED - Widget Association Forum 2018</div>
  <meta property="eventStatus" content="http://schema.org/EventCancelled" />
  <div class="event-venue" property="location" typeof="Place">
    <span property="name">Grand Lake Center</span>
    <div class="address" property="address" typeof="PostalAddress">
      <span property="streetAddress">301 Marina Dr.</span><br>
      <span property="addressLocality">Grand Lake</span>,
      <span property="addressRegion">CO</span>
      <span property="postalCode">80447</span>
    </div>
  </div>
 </span>
</div>

Acknowledgements

My thanks to Richard Wallis for his help with this article.

Latest Images

Trending Articles

Latest Images