GoodRelationsSimple

From Wiki of the E-Business and Web Science Research Group
Jump to: navigation, search
gr_banner_small.png
GoodRelations is a standardized vocabulary for product, price, and company data that can be embedded into existing static and dynamic Web pages.

Project Main Page
Vocabulary
Documentation
Developer's Wiki
GoodRelations Cookbook

GoodRelations Simple Recipe

Overview

On this page, we explain how a typical business would use the GoodRelations vocabulary for e-commerce to add rich meta-data to their Web pages so that state-of-the art search engines, matchmaking services, and recommender systems will find your company.

Scenario Description

In the example, we use the following content:

  • The URI of the company's main page is
    http://www.example.com/xyz
  • The legal name of the business is
    Hepp Industries Ltd.
  • The address of the shop and the main office are the same.
  • The opening hours given in CET (GMT+1:00) are
    8:00 - 18:00 Mon-Fri and
    8:30-14:00 on Saturdays. 
  • The company offers
    to sell and
    to repair
    "computers and motorbikes". This is represented by the two strings "We sell and repair computers and motorbikes" and "computers and motorbikes".
  • The offer is valid from 2009-04-24T00:00:00+01:00 through 2010-04-24T00:00:00+01:00.

The language of the short text "computers and motorbikes" is English (@en).

Publishing the Rich Meta-Data

There are at least three ways of adding such rich meta-data to your page:

  1. You can simply insert additional, invisible RDFa markup into your HTML page, most likely directly before the closing "body" element. This is the easiest way.
  2. You can create a dedicated file "goodrelations.rdf" in the RDF/XML format, upload it to your Web server, and link to that file from your Web page. The necessary steps are described here.
  3. You can create a dedicated textfile "goodrelations.n3" in the N3/Turtle format and proceed as in alternative 2. N3/Turtle is just more readable for humans.

UML Diagram

The following shows the relevant subset from the full UML diagram of GoodRelations:

alt UML diagram of the GoodRelations subset for the simple example

Example in RDFa

Insert the following additional mark-up directly before the closing </body> in your Web page, i.e.

<xml> ... <body>

We sell and repair computers and motorbikes

<div xmlns="http://www.w3.org/1999/xhtml"

 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"

... SNIPPET FROM BELOW ...

</div> </body> </html> </xml>

Here is the complete snippet to be used for our example:

<xml>

   <span rel="foaf:page" resource=""/>
   <span property="gr:legalName" content="Hepp Industries Ltd." datatype="xsd:string"/>
   <span rel="gr:hasPOS" resource="http://www.example.com/xyz#myShop"/>
   
     <span rel="foaf:page" resource=""/>
     
         <span rel="foaf:page" resource=""/>
         
           <span property="gr:closes" content="14:00:00" datatype="xsd:time"/>
           <span rel="gr:hasOpeningHoursDayOfWeek" resource="http://purl.org/goodrelations/v1#Saturday"/>
           <span property="gr:opens" content="08:30:00" datatype="xsd:time"/>
         
         
           <span property="gr:closes" content="18:00:00" datatype="xsd:time"/>
           <span rel="gr:hasOpeningHoursDayOfWeek" resource="http://purl.org/goodrelations/v1#Friday"/>
           <span rel="gr:hasOpeningHoursDayOfWeek" resource="http://purl.org/goodrelations/v1#Thursday"/>
           <span rel="gr:hasOpeningHoursDayOfWeek" resource="http://purl.org/goodrelations/v1#Wednesday"/>
           <span rel="gr:hasOpeningHoursDayOfWeek" resource="http://purl.org/goodrelations/v1#Tuesday"/>
           <span rel="gr:hasOpeningHoursDayOfWeek" resource="http://purl.org/goodrelations/v1#Monday"/>
           <span property="gr:opens" content="08:00:00" datatype="xsd:time"/>
         
     
     <span property="rdfs:comment" content="We sell and repair computers and motorbikes" xml:lang="en"/>
     <span rel="gr:hasBusinessFunction" resource="http://purl.org/goodrelations/v1#Repair"/>
     <span rel="gr:hasBusinessFunction" resource="http://purl.org/goodrelations/v1#Sell"/>
     
        <span rel="foaf:page" resource=""/>
        <span property="rdfs:comment" content="computers and motorbikes" xml:lang="en"/>
     
     <span property="gr:validFrom" content="2009-04-24T00:00:00+01:00" datatype="xsd:dateTime"/>
     <span property="gr:validThrough" content="2010-04-24T00:00:00+01:00" datatype="xsd:dateTime"/>
   

</xml>

Ideally, you should also change the DOCTYPE in the header to "XHTML+RDFa":

<xml> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> </xml>

Also, make sure that the "head" element includes the proper content type and encoding for XHTML:

<xml> <head>

 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8"/>
 <title>Hepp Industries Ltd. Main Page</title>

</head> </xml>

So the complete header should look like

<xml> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

 <head>
   <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8"/>
   <title>Hepp Industries Ltd. Main Page</title>
 </head>
 <body>

... </xml>

Example in N/Turtle

Create a new text file "goodrelations.n3" with the following content, upload it to your Web server, and link to that file from your Web page. The necessary steps are described here.

@prefix foo: <http://www.example.com/xyz#> .
@prefix gr: <http://purl.org/goodrelations/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix foaf: <xmlns:foaf="http://xmlns.com/foaf/0.1/> .

# Simple Example: Business Entity, Shop, and High-Level Descrition of Offers
foo:myCompany
	a gr:BusinessEntity ;
	foaf:page <http://www.example.com/xyz>;
	gr:legalName "Hepp Industries Ltd."^^xsd:string ;
	gr:hasPOS foo:myShop ;
	gr:offers foo:myOffering .
# The following three elements are the same as in the minimal example
foo:myShop
	a gr:LocationOfSalesOrServiceProvisioning ;
	foaf:page <http://www.example.com/xyz>;
	gr:hasOpeningHoursSpecification
		foo:Workdays,
		foo:Saturdays .
foo:Workdays
	a gr:OpeningHoursSpecification ;
	gr:opens "08:00:00"^^xsd:time ;
	gr:closes "18:00:00"^^xsd:time ;
	gr:hasOpeningHoursDayOfWeek
		gr:Monday, gr:Tuesday, gr:Wednesday, gr:Thursday, gr:Friday .
foo:Saturdays
	a gr:OpeningHoursSpecification ;
	gr:opens "08:30:00"^^xsd:time ;
	gr:closes "14:00:00"^^xsd:time ;
	gr:hasOpeningHoursDayOfWeek gr:Saturday .
# The following elements are in addition to those from the minimal example
foo:myOffering
	a gr:Offering;
	foaf:page <http://www.example.com/xyz>;
	rdfs:comment "We sell and repair computers and motorbikes"@en ;
	gr:includes foo:myProducts ;
	gr:hasBusinessFunction gr:Sell, gr:Repair ;
	gr:validFrom "2009-04-24T00:00:00+01:00"^^xsd:dateTime ;
	gr:validThrough "2010-04-24T00:00:00+01:00"^^xsd:dateTime ;
	gr:availableAtOrFrom foo:myShop .

foo:myProducts
	a gr:ProductOrServicesSomeInstancesPlaceholder;
	foaf:page <http://www.example.com/xyz>;
	rdfs:comment "computers and motorbikes"@en.
# one can attach more details on the products, see later


Example in RDF/XML

Create a new file "goodrelations.rdf" in the RDF/XML format with the following content, upload it to your Web server, and link to that file from your Web page. The necessary steps are described here.

<xml> <?xml version="1.0"?> <rdf:RDF xmlns:gr="http://purl.org/goodrelations/v1#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:foo="http://www.example.com/xyz#" xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">

 <gr:BusinessEntity rdf:about="http://www.example.com/xyz#myCompany">
   <gr:legalName rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Hepp Industries Ltd.</gr:legalName>
   <gr:hasPOS>
     <gr:LocationOfSalesOrServiceProvisioning rdf:about="http://www.example.com/xyz#myShop">
       <gr:hasOpeningHoursSpecification>
         <gr:OpeningHoursSpecification rdf:about="http://www.example.com/xyz#Workdays">
           <gr:opens rdf:datatype="http://www.w3.org/2001/XMLSchema#time">08:00:00</gr:opens>
           <gr:closes rdf:datatype="http://www.w3.org/2001/XMLSchema#time">18:00:00</gr:closes>
           <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Monday" />
           <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Tuesday" />
           <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Wednesday" />
           <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Thursday" />
           <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Friday" />
         </gr:OpeningHoursSpecification>
       </gr:hasOpeningHoursSpecification>
       <gr:hasOpeningHoursSpecification>
         <gr:OpeningHoursSpecification rdf:about="http://www.example.com/xyz#Saturdays">
           <gr:opens rdf:datatype="http://www.w3.org/2001/XMLSchema#time">08:30:00</gr:opens>
           <gr:closes rdf:datatype="http://www.w3.org/2001/XMLSchema#time">14:00:00</gr:closes>
           <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Saturday" />
         </gr:OpeningHoursSpecification>
       </gr:hasOpeningHoursSpecification>
     </gr:LocationOfSalesOrServiceProvisioning>
   </gr:hasPOS>
   <gr:offers>
     <gr:Offering rdf:about="http://www.example.com/xyz#myOffering">
       <rdfs:comment xml:lang="en">We sell and repair computers and motorbikes</rdfs:comment>
       <gr:includes>
         <gr:ProductOrServicesSomeInstancesPlaceholder rdf:about="http://www.example.com/xyz#myProducts">
           <rdfs:comment xml:lang="en">computers and motorbikes</rdfs:comment>
         </gr:ProductOrServicesSomeInstancesPlaceholder>
       </gr:includes>
       <gr:hasBusinessFunction rdf:resource="http://purl.org/goodrelations/v1#Sell" />
       <gr:hasBusinessFunction rdf:resource="http://purl.org/goodrelations/v1#Repair" />
       <gr:validFrom rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2009-04-24T00:00:00+01:00</gr:validFrom>
       <gr:validThrough rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2010-04-24T00:00:00+01:00</gr:validThrough>
       <gr:availableAtOrFrom rdf:resource="http://www.example.com/xyz#myShop" />
     </gr:Offering>
   </gr:offers>
 </gr:BusinessEntity>

</rdf:RDF> </xml>

Extensions and Improvements

You can improve the rich meta-data in many ways.

Translations of Text Elements

You can provide translations of the strings "computer and motorbikes" and "We sell and repair computers and motorbikes", indicate the respective language tag, and attach the translations to both the gr:Offering and gr:ProductOrServiceSomeInstancesPlaceholder nodes.

Example: <xml>

   <span property="rdfs:comment" content="computers and motorbikes" xml:lang="en"/>
   <span property="rdfs:comment" content="Computer und Motorräder" xml:lang="de"/>
   <span property="rdfs:comment" content="ordinateurs et motocyclettes" xml:lang="fr"/>

</xml>

Payment Methods

You can indicate which payment methods you accept by attaching those to the gr:Offering node:

<xml>

             <div rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#MasterCard"/>
             <div rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#VISA"/>

... </xml>

Available payment methods are

  • AmericanExpress
  • DinersClub
  • Discover
  • MasterCard
  • VISAByBankTransferInAdvance
  • ByInvoice
  • COD
  • Cash
  • CheckInAdvance
  • DirectDebit and
  • PayPal.

For understanding the full range of options, please see the GoodRelations Primer.

Contact Details

You can attach the address and geo position of your main office and of your shop or shops to the respective elements. If you don't know the latitude and longitude of your addresses, you can easily use online services to determine them, e.g. the excellent one by Stephen P. Morse at http://stevemorse.org/jcal/latlon.php.

Important: Note that this also requires to define the namespace prefiyx "vcard:" as "http://www.w3.org/2006/vcard/ns".

Office

<xml>

   <span property="gr:legalName" content="Hepp Industries Ltd." datatype="xsd:string"/>
   
     
     <span property="vcard:street-address" content="1234 Hepp Road"/>
     <span property="vcard:postal-code" datatype="xsd:string" content="85577"/>
     <span property="vcard:locality" content="Neubiberg"/>
     <span property="vcard:region" content="Bavaria"/>
     <span property="vcard:country-name" content="Germany"/>
   
   <span property="vcard:tel" datatype="xsd:string" content="+49-89-6004-0"/>
   
     <span property="vcard:latitude" datatype="xsd:float" content="48.0802626"/>
     <span property="vcard:longitude" datatype="xsd:float" content="11.6407428"/>
   
   <span rel="gr:hasPOS" resource="http://www.example.com/xyz#myShop"/>

</xml>

Shop

<xml>

   
     
     <span property="vcard:street-address" content="1234 Hepp Road"/>
     <span property="vcard:postal-code" datatype="xsd:string" content="85577"/>
     <span property="vcard:locality" content="Neubiberg"/>
     <span property="vcard:region" content="Bavaria"/>
     <span property="vcard:country-name" content="Germany"/>
   
   <span property="vcard:tel" datatype="xsd:string" content="+49-89-6004-0"/>
   
     <span property="vcard:latitude" datatype="xsd:float" content="48.0802626"/>
     <span property="vcard:longitude" datatype="xsd:float" content="11.6407428"/>
   
    

</xml>

owl:imports

You can improve the ability of intelligent Web applications to reason about your data if your properly import the GoodRelations and vCard ontologies.

RDFa

<xml>

     <span rel="owl:imports" resource="http://purl.org/goodrelations/v1"/>
     <span rel="owl:imports" resource="http://www.w3.org/2006/vcard/ns"/>

</xml>

N3

<>
    a    owl:Ontology;
    owl:imports
       <http://purl.org/goodrelations/v1>, <http://www.w3.org/2006/vcard/ns>.

RDF/XML

<xml> <?xml version="1.0"?> <rdf:RDF xmlns:gr="http://purl.org/goodrelations/v1#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:foo="http://www.example.com/xyz#" xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">

 <rdf:Description rdf:about="http://www.example.com/xyz#">
       <rdf:type rdf:resource="http://www.w3.org/2002/07/owl#Ontology"/>
       <owl:imports rdf:resource="http://purl.org/goodrelations/v1"/>
       <owl:imports rdf:resource="http://www.w3.org/2006/vcard/ns"/>
   </rdf:Description>

</xml>

Query Example

Query Examples