From Wiki of the E-Business and Web Science Research Group
Jump to: navigation, search



GoodRelations: An Ontology for Describing Web Offers

Primer and User’s Guide

Draft 2008-11-27

This version:

Previous version:

Latest version:

Author: Martin Hepp, (c) 2008 by Martin Hepp,

This documentation is available under a Creative Commons Attribution-No Derivative Works 3.0 Germany License. You are free to use and distribute this document as long as it remains unchanged. Note that this license applies only to the documentation. The GoodRelations ontology itself is available under a Creative Commons Attribution 3.0 license, which allows derived works etc.


A promising application domain for Semantic Web technology is the annotation of products and services offers on the Web so that consumers and enterprises can search for suitable suppliers more easily and more precisely, and so that retailers can easily reuse product model data from manufacturers. GoodRelations is a lightweight, generic vocabulary for the Semantic Web that allows expressing all typical aspects of offers for goods and services on the Web. For example, we often want to be able to express that a particular Web site describes an offer to sell cell phones of a certain make and model at a certain price, that a piano house offers maintenance for pianos that weigh less than 150 kg, or that a car rental company leases out cars of a certain make and model from a particular set of branches across the country.

The GoodRelations ontology provides a generic yet lightweight vocabulary for describing in a machine-readable way the details of offers made on the Semantic Web. This allows vendors to add a machine-readable definition of their offers so that Semantic Web search engines can find such Web resources more precisely. It empowers them to return exactly matching offers for a given need.

Such is in the interest of shop owners and manufacturers, because it makes sure the particular features and strengths of their products or services are considered by Semantic Web search engines, and it is in the interest of buyers, because it allows them to find offers that exactly fit their requirements. In addition, GoodRelations makes it easy to exchange product model details and feature data between manufacturers and shop operators, so that such data can be reused more easily along the value chain.


This primer is a draft, reflecting the current version v1 of the GoodRelations ontology available at It complements the eClassOWL ontology and eClassOWL User’s Guide. Important: The last official release 5.1 of eClassOWL requires a few small modifications in order to be fully compatible with GoodRelations. The current official release available at does not yet meet this requirement. However, an updated version 5.1.4 is already available for download at The only reason why this is not yet currently linked at the eClassOWL project Web page is that the documentation is not yet updated. We expect to finish that soon. In the meantime, you can safely use eClassOWL 5.1.4 with GoodRelations. The ontology itself is already final.


The ontology and documentation are provided as they are, without warranty of any kind, expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the ontology or its documentation or the use or other dealings in the ontology or documentation.



  1.1 Need for a Common Vocabulary for Web Offers
  1.2 What does GoodRelations contribute?

  2.1 Minimal Example
  2.2 Motivating Scenarios

  3.1 Preliminaries: Header and Namespace Definition
  3.2 Finding Suitable Unique Identifiers
  3.3 Step 1: Business Entity
  3.4 Step 2: Products and Offerings
  3.5 Step 3: Eligible Customers and Regions
  3.6 Step 4: Price Specifications
  3.7 Step 5: Delivery Options and Delivery Charge Specifications
  3.8 Step 6: Payment Options and Payment Charge Specifications
  3.9 Step 7: Warranty Promises
  3.10 Step 8: Bundles
  3.11 Step 9: Services and Value Ranges
  3.12 Step 10: Shop Locations and Opening Hours
  3.13 Step 11: Consumables, Accessories, Spare Parts, and Similar Products

  4.1 Find all known business entities and their legal names
  4.2 Who sells cell phones and on which Web pages can I get more information on respective offerings?
  4.3 Which offers of cell phones exists, what is the price, and where can I find the offering on the Web?


  5.1 Handling of Ranges and Intervals
  5.2 Products and Services: Models, Classes, and Instances



In this section, we explain why GoodRelations is practically relevant and what it actually contributes.

1.1 Need for a Common Vocabulary for Web Offers

Imagine, you are searching for a particular type of product or service on the Web. Using standard search engines like Google or others can be a frustrating experience. This is for a number of reasons. First, when searching, you have to know and use the very same words and the same language as the vendor uses for describing the offer. If you search for “TV”, you won’t find pages that use “television”, for instance. Second, you have no means for narrowing down your search to offers that meet certain criteria, for example, a minimal screen size, or a certain type of interface. Such criteria can also refer to the commercial side. For example, you are usually looking for suppliers who actually ship to your country and serve your type of business. Particularly unsatifying is current search when your search is based on a less common meaning of a very popular term (thanks to Peter Mika for this good example), or if you have a special requirement that most of the offers do not meet.

While search for suitable suppliers is the most obvious use case, it is by far not the only one in which current Web technology is deficient. Basically, the vast amount of product data exchange via the Web page is very unsatisfying from a data management perspective. It requires a lot of human labor for extracting and pasting data element by element from a Web page to an in-house system, and for “stupid” information processing, like unit conversion or summing up two values. While there exist standardized classification schemas for products and services like UNSPCS and eClass, and even a fully-fledged OWL variant of the latter, they cannot be used for describing your offers or your needs.

Also, operators of Web shops have a hard time keeping their description of commodity items consistent with those on the vendors’ pages. Only if individual agreements are established, data can be exchanged and processed easily based on XML schemas.

In short, the potential of the Web as the largest collection of persistently published product data for better search and data exchange remains unexploited, because the structure and meaning of this data is lost in the transmission.

1.2 What Does GoodRelations Contribute?

GoodRelations is a lightweight yet sophisticated vocabulary that allows manufacturers and shop operators to express the exact meaning of their offers made on the Web in a machine-readable way. This empowers search engines to support more precise search, and partners in the value chain to automate their content integration tasks.

GoodRelations complements the eClassOWL ontology, which is the first non-toy ontology for products and services. The latest version of eClassOWL provides more than 30,000 product classes and more than 5,000 attributes for describing product features. The relationship between these two ontologies is straightforward:

  • eClassOWL provides classes, attributes, and values for describing what a product or service is.
  • GoodRelations provides everything needed for describing the actual offer and its details, i.e., the relationship between a business entity and a product or service. That is also the origin of the name – it’s an ontology for the relations between goods and business entities.

While eClassOWL is the largest ontology for products and services, one can use any other products or services ontology in combination with GoodRelations. Only a few guidelines must be met.

For example, the Austrian ebSemantics initiative is close to release several products and services ontologies for particular domains (events, tickets, accommodation, etc.) that will be GoodRelations-compliant.

There are also situations in which we cannot or do not want to refer to dedicated products or services ontologies. In that case, one can still use GoodRelations. See Recipe 2 for more details.

While GoodRelations is moderate in size, it is the outcome of about five years of work in progress, carried out at multiple institutions. The main features of GoodRelations are as follows:

  • Based on currently available Semantic Web standards, tools, and infrastructure (“ready to run as of today”)
  • Minimal requirements on reasoner support – any RDF-S-style reasoner, OWL DLP, DL, or ter-Horst reasoner will work. At the same time, GoodRelations remains within OWL DL and can thus be used for consistent DL reasoning.
  • Support for all common business functions, like buy, sell, lease, dispose, repair, etc.
  • Suits both for explicit instances, product models, and anonymous instances
  • Supports different prices for different types of customers or quantities
  • Supports product bundles in combination with any kinds of units of measurements (“2 kg butter plus 2 cell phones for € 99” would be no problem)
  • Supports price specifications both as single values or price ranges
  • Supports intervals and units of measurements for product features
  • Compatible with eClassOWL and other ontologies
  • Supports ISO 4217 currencies
  • Supports defining eligible regions
  • Supports common delivery and shipping methods
  • Supports specifying accepted payment methods
  • Offerings can be constrained to certain eligible business entities (e.g. resellers only)
  • Supports warranty promises, i.e., the duration and scope
  • Supports charges for certain payment or delivery options; the latter also individually per region
  • Compatible with international standards: ISO 3166, ISO 4217, UN/CEFACT, eCl@ss, etc.


In the following, we give a minimal example of using GoodRelations, followed by a comprehensive list of typical, more complex scenarios.

2.1 Minimal Example

Let’s assume the following simple scenario: „The shop at the Web page offers to sell a single instance of a TV set that has a screen size of 30 centimeters, via this page, for 200 Euros.” If we want to express that properly, we have to model three parts:

  • First, there is a business entity named
  • Second, there exists a single TV set that has a screen size of 30 centimeters.
  • Third, there is an offer made by the Business entity to SELL this particular TV set for 200 Euros.

Before we proceed, we have to discuss the role of the URI a little bit more. As long as a Web page is only being viewed in a Web browser, the same URI may be used to refer to multiple different things – can be employed to point people

  • to the company,
  • to the offering, or
  • to the product description.

The Semantic Web requires that different things have different identifiers, so that computers can keep them apart. So we cannot use as identifiers for all three parts (at most, we can use it for one of them). The cleanest way is to define individual identifiers for every distinct thing, and link them back via the rdfs:seeAlso property to a Web page that contains a combined description. This allows people to look up the Web page with human readable content easily without tangling items that must have separate identifiers for computer processing.

This aspect is described in more details in sections 3.3.1 and 3.3.2 of the GoodRelations Technical Report.

In the following example, we simply define new identifiers within the following namespace:

We will use the N3 notation for all subsequent examples because it allows breaking down statements into logical parts more easily than RDF/XML.

Now, in order to express the offering using GoodRelations, we have to do the following.

a) Step 1: Define the relevant name spaces and prefixes

@prefix toy: <> .
@prefix gr: <> .
@prefix xsd: <> .
@prefix default: <> .
@prefix rdfs: <> .
@prefix rdf: <> .
@prefix owl: <> .

b) Step 2: 'Choose a products and services ontology to describe the product and import GoodRelations'

In order to describe the types and features of the actual products or services being offered, you need to import and refer to a respective ontology. In real scenarios, a good choice is eClassOWL. You could also create your own vocabularies for specific types of products and their features following these instructions.

In the following, we will use a toy ontology available at

for reasons of simplicity. That ontology defines four types of products, namely the classes

toy:ComputerMouse, and

plus a few product feature attributes, like the quantitative propertieshasScreenSize, hasSize, hasWeight, and hasOperatingValue; and the qualitative property hasInterfaceType plus respective pre-defined values, which are not used in here.

So we import GoodRelations and the toy ontology:

a owl:Ontology ;
owl:imports <> ,
<> .

c) Step 3: Describe the business entity

a gr:BusinessEntity ;
rdfs:seeAlso <> ;
gr:legalName " Ltd."^^xsd:string.

d) Step 4: Describe all things that are being offered (not yet the offer itself, just the items)

First we say that mySony100Set is a TV set, and then we say that it is an actual TV set, not a make and model or a set of unknown instances (see section 5.2. for more details). Then we say that its screen size is defined by the value QuantitativeValueFloat_1, which holds the unit of measurement (“CMT” is the UN/CEFACT code for centimeters) and the actual amount (“30.0”). This may sound a bit complex for some readers but is caused by limitations of the OWL language. For background information, see section 3.4.2 of the GoodRelations Technical Report.

a toy:TVSet , gr:ActualProductOrServiceInstance ;
toy:hasScreenSize default:QuantitativeValueFloat_1.

a gr:QuantitativeValueFloat ;
"CMT"^^xsd:string ;
gr:hasValueFloat "30.0"^^xsd:float .

e) Step 5: Describe the offer and link the offer to the business entity making it

First, we must express that there is an offer to sell something and that what is being offered is described in TypeAndQuantityNode_1. Also, we have to attach UnitPriceSpecification_1 to specify the price:

a gr:Offering ;
gr:Sell ;
default:UnitPriceSpecification_1 ;
gr:includesObject default:TypeAndQuantityNode_1 .

Then we must say that is making that offer: default:ElectronicsCom gr:offers default:Offering_1 .

Then we must say what is part of the offering. In our case it is “one piece of my TV set”. In another case it could also be 500 ml of milk or 350 kg of coal, or a bundle of both. The quantity is specified by a float value for the amount and a string for the unit of Measurement as an UN/CEFACT Common Code. The code for piece or item is “C62”. The full list is given in the Annex.

a gr:TypeAndQuantityNode ;
gr:amountOfThisGood "1.0"^^xsd:float ;
"C62"@en ;
gr:typeOfGood default:mySony100TVSet .

Now we must say that the price is 200 Euros per one piece of this bundle. The currency is encoded using the ISO 4217 standard (3 characters, “EUR” for Euro). C62 means one piece of the bundle.

a gr:UnitPriceSpecification ;
gr:hasCurrency "EUR"^^xsd:string ;
gr:hasCurrencyValue "200.0"^^xsd:float ;
"C62"^^xsd:string .

That’s it. You have just encoded the offering from above in a machine-readable form. The complete RDF graph is shown in Figure 1 below.


Figure 1. RDF graph of the minimal example