Strategy: Assessing when to use a Data Item, a Link, or Text input for a Schema.org property

Modified on Mon, 6 Apr at 8:29 PM

Sometimes it is hard to decide what to add in a property field of the Editor or Highlights. The answer will depend on the Schema.org vocabulary and your knowledge graph strategy.

This support article will help you asses whether you should target a URL, text, or a data item, or another data type.

TABLE OF CONTENTS

How does the Schema.org tell me to specify text, a URL or a Data Item?
- Are there specific rules I should follow?
- Why does it matter that I follow these rules?
What happens when a property expects more than one DataType or Type?
Conclusion

How does the Schema.org tell me to specify text, a URL or a Data Item?

Schema.org vocabulary defines properties, Types and DataTypes. A Type is an entity (e.g. Thing and its subtypes), while DataTypes are simple categories of data (e.g. Booleans, Strings, Integers, URLs, etc). In the documentation, every property will specify what kinds of data it will accept (e.g. "name" will accept Text, sameAs will accept URL, offers will accept Offer type, etc).

Are there specific rules I should follow?

Always use only a Type or Datatype that a property expects. You can see what a property expects in the Expected Type column or under the header "Value Expected to be one of these types"

For example:  Don't nest a Product under "offers". Instead, you would use the full property path "offers~Offer~itemOffered~Product"

The human way we think about Products and pricing needs to be translated into the specific structured format of Schema.org. This involves "translating" the information using the defined rules about what a property can and will accept. Learning these rules is a skill and comes with practice.

Why does it matter that I follow these rules?

Choosing the correct format impacts how your knowledge graph is formed. An accurate and correct knowledge graph will support search and answer engine optimization and help generate grounded and goverened LLM responses.

What happens when a property expects more than one DataType or Type?

This is when the translation work gets fun. When authoring schema markup in the Schema App Editor, users frequently encounter decisions about how to represent values for properties. As a general rule:

Use a Data Item for entities you want to define and connect internally (and where required)
Use URLs when you want to reference entities you do not care to define internally (and where required)
Use Text for simple, non-entity values (and where required)

Whenever possible, use data items whenever you are describing a distinct entity that could be referenced elsewhere in your markup. This enables stronger connections within your knowledge graph.

What's the difference between referencing a data item and just plain text?

Using data items you can build a connected knowledge graph by linking entities together using URIs. Adding plain text does not allow you to define the meaning of your data or connect it to other data.

Example: The “author” property

The author property can accept either Text or Person (typed data item). Technically both are valid.
However:

Using Text (e.g. “Jane Smith”) provides minimal context
Using a Person data item allows you to define who Jane Smith is and connect her to other entities

In most cases, using a Person data item is the recommended approach. The next best option is to reference a URL or URI. The last is text.

Note: The exception to this rule is when text or another data type (e.g. Duration, Date) is the only expected format.

What's the difference between referencing a data item and referencing a URL?

In general, if the entity matters enough to be on your website, it should likely be in your knowledge graph. However, URLs are a great way to reference real-world entities (e.g, Organizations, Products, CreativeWorks, etc) that are better described by other external authoritative knowledge graphs or sources.

Why does the Schema Markup Validator turn @ids into "Thing" data items with names?

This quirk of the Validator is a commonn point of confusion. When JSON-LD references a URL/URI and the property can accept a Data Item, and a URL, the Validator has a quirk of turning that URL into the most generic Type that property accepts. The URL becomes the "name" of that entity". In reality, the machines processing your data will be treating URIs and URLs like the gateways to other context rich information. Don't stress about this quick, as long as you're following Schema.org best practices.

**When must I create a Data Item instead of pasting a link?**

Some properties require a Data Item to be added (e.g. owner, publisher, brand).

In Schema.org, that will look like documentation where the Expected Type column or section only shows Types.

Note: recall that the syntax for Schema.org is that Types follow Pascal Case formatting while properties follow camelCase formatting.

If some Data Types expect a data item, why does Schema App sometimes just reference URIs?

Excellent question and a great opportunity to bring up heuristic of the "Three Hops Rule" Schema App Editor markup is deployed with the heuristic that if markup "belongs to" a different URL than the one being targeted AND that data item is nested more than three levels deep, then we will only reference the URI of that data item. This keeps us from accidentally deploying your whole connected knowledge graph to one page.

The drawback to that choice is that sometimes you'll run into the behaviour in the Validator or Rich Results test described in the section titled: Why does the Schema Markup Validator turn @ids into "Thing" data items with names?

Conclusion

As a general rule:

Use data items whenever possible, especially if the entity is mentioned more than once on your website
Use URLs when you want to reference entities you do not care to define internally, and where required
Use Text where required, typically for simple non-rich content (e..g names, labels)
Look out for the other DataTypes (Boolean, Date, Duration, etc)