GoodRelations and Microdata Syntax

The GoodRelations Cookbook
Recipe GoodRelations and Microdata Syntax
Description GoodRelations and the syntaxes it can be used with
Status mature
Level intermediate
Tags microdata, rdfa, rdf, xml, turtle, json, gdata, odata

While many Web vocabularies are tied to a single syntax, GoodRelations can be used in a variety of syntaxes, namely

  • RDFa,
  • Microdata,
  • Turtle (RDF),
  • RDF/XML (RDF),
  • JSON,
  • GData, and
  • OData.

For Web developers, RDFa and Microdata are the most important ones. We do not want to enter the discussion whether one of the two is better on this page, since both can be used in similar ways. In short one can say that

  • RDFa integrates better into the larger W3C Semantic Web technology stack while
  • Microdata has significant advantages from the perspective of adding meta-data to HTML markup.

Overview

The main difference between using GoodRelations in Microdata and in RDFa is that you use just the local part of a property identifier (e.g. legalName for http://purl.org/goodrelations/v1#legalName) when inside the scope of a GoodRelations class as the type of a node.

When using a GoodRelations property within the scope of an external type (e.g. http://schema.org/Offer) or when using an externally defined property within the scope of a GoodRelations type, you must use the full URI (e.g. http://schema.org/telephone).

Microdata does not support "compact" URIs (CURIES) in the form

prefix:local_part

(e.g gr:legalName).

Example:

<div itemscope itemtype="http://purl.org/goodrelations/v1#BusinessEntity">
<span itemprop="legalName">ACME Bagel Bakery Ltd.</span>
Contact Details:
Tel: <span itemprop="http://schema.org/telephone">+49-89-12345678-0</span>,
</div>

Scenario 1: Using GoodRelations in Microdata syntax

You can use GoodRelations directly in Microdata syntax:

<div itemscope itemtype="http://purl.org/goodrelations/v1#Offering" itemid="#offer">
<div itemprop="name">Hepp Personal SCSI Controller Card</div>
<div itemprop="description">The Hepp Personal SCSI is a 16-bit
add-on card that allows attaching up to seven SCSI devices to your computer.</div>
<link itemprop="hasBusinessFunction" href="http://purl.org/goodrelations/v1#Sell" />
<div itemscope itemprop="hasPriceSpecification"
itemtype="http://purl.org/goodrelations/v1#UnitPriceSpecification">Price:
<meta itemprop="hasCurrency" content="USD">$
<span itemprop="hasCurrencyValue">99.99</span>
<time itemprop="validThrough" datetime="2012-11-30T23:59:59Z"></time>
</div>
Condition: <div itemprop="condition">used</div>
EAN/UPC: <span itemprop="hasEAN_UCC-13">1234567890123</span>
MPN: <span itemprop="hasMPN">PSCSI</span>
Article No. <span itemprop="hasStockKeepingUnit">123-456</span>
Availability: <span itemscope itemprop="hasInventoryLevel"
itemtype="http://purl.org/goodrelations/v1#QuantitativeValue">
<meta property="hasMinValue" content="1">In-stock
</span>
</div>

Scenario 2: Using GoodRelations properties to extend schema.org types

You can use GoodRelations elements to extend schema.org types by details that are not covered by schema.org, e.g. shipping charges or eligible countries. In that case you have to use the full URIs for properties that are provided by GoodRelations when used to augment schema.org types. As soon as the type to which you apply the property is again from GoodRelations, you can use the local part of the property names. See the following example in which

<div itemscope itemtype="http://schema.org/Offer" itemid="#offer">
<div itemprop="name">Hepp Personal SCSI Controller Card</div>
<div itemprop="description">The Hepp Personal SCSI is a 16-bit add-on card that allows
attaching up to seven SCSI devices to your computer.</div>
<link itemprop="http://purl.org/goodrelations/v1#hasBusinessFunction"
href="http://purl.org/goodrelations/v1#Sell" />
<!-- Shipment fees -->
Delivery costs to
<div itemscope itemprop="http://purl.org/goodrelations/v1#hasPriceSpecification"
itemtype="http://purl.org/goodrelations/v1#DeliveryChargeSpecification">
<meta itemprop="eligibleRegions" content="DE">Germany:
<meta itemprop="hasCurrency" content="EUR">Euro:
<span itemprop="hasCurrencyValue">10.00</span>
<link itemprop="appliesToDeliveryMethod"
href="http://purl.org/goodrelations/v1#UPS" />(via UPS)
</div>
<!-- other offer properties follow here -->
...
</div>

Scenario 3: Using schema.org properties to extend GoodRelations types

You can used schema.org properties and types in combination with GoodRelations types. This is in particular recommended for attaching images, addresses, and geo-location information information, because such will then all come from a single complementing vocabulary instead of from various Web vocabularies (vCard, geo, WGS84, FOAF, ...).

<div itemscope itemtype="http://purl.org/goodrelations/v1#BusinessEntity">
<span itemprop="legalName">ACME Bagel Bakery Ltd.</span>
Contact Details:
<div itemscope itemprop="http://schema.org/address"
itemtype="http://schema.org/PostalAddress">
Main address:
<span itemprop="streetAddress">Bagel Street 1234</span>
<span itemprop="postalCode">12345</span>
<span itemprop="addressLocality">Munich, Germany</span>
</div>
<!-- The following properties use full URIs because they are attached
to a **GoodRelations type** but come from schema.org -->
Tel: <span itemprop="http://schema.org/telephone">+49-89-12345678-0</span>,
Fax: <span itemprop="http://schema.org/faxNumber">+49-89-12345678-99</span>,
E-mail: <span itemprop="http://schema.org/email">contact@example.org</span>
<link itemprop="http://schema.org/url" href="http://www.acme-bagels.com/" />
</div>

Scenario 4: Using GoodRelations from the schema.org Namespace

We are working with the schema.org sponsors, namely Google, Yahoo, Bing, and Yandex, on the integration of GoodRelations into the schema.org core. This will mean that you can use the full expressivity of GoodRelations directly from the schema.org namespace in Microdata syntax soon. A preview of the resulting markup is here. Stay tuned!

Note: This will be an additional syntactical form of using GoodRelations for your site. GoodRelations will remain an independent vocabulary, and in RDFa and other RDF syntaxes, the original namespace of GoodRelations will remain the primary location.

Links:

Official Microdata Processing Rules

The official Microdata processing rules for GoodRelations are now part of the GoodRelations specification.

RDF Representation of GoodRelations from Microdata Markup

If you parse GoodRelations data in Microdata syntax, the URIs for all properties should be built by directly attaching the local part of a property (e.g. legalName) to the base URI of the vocabulary (http://purl.org/goodrelations/v1#).

So the URI of the legalName property from the example above should be http://purl.org/goodrelations/v1#legalName.

by Martin Hepp