Documentation/Conventions

From GoodRelations Wiki
Jump to: navigation, search

Conventions for the User's Guide

In the next sections, we explain the conceptual structure of the GoodRelations vocabulary (and thus of the e-commerce model in schema.org). On this page, we define the conventions for illustrations and other elements.

Illustrations of Conceptual Structures

In essence, GoodRelations is a conceptual model that defines entity types, relationship types, enumerated values, and hierarchical relations among entity types and among properties. Since GoodRelations can be used in many different syntaxes, both RDF-based syntaxes and other popular syntaxes, we use a special type of diagram for illustrating the conceptual elements and how they relate. The notation is more concise than typical RDF graph visualizations, and more intuitive for RDF and JSON developers than e.g. UML class diagrams (for classes) or UML object diagrams (for instances).

  • Entities are shown as circles.
  • They are labeled with a short characterization in plain English (like "Offer") in boldface and the official keyword/URI as a CURIE (e.g. gr:Offering) directly below. Since there can be naming differences between GoodRelations and schema.org for the same element in the two namespaces, the schema.org variant is also always given and marked in red (e.g. schema:Offer). A CURIE is a compact form of writing down URIs by substituting the often long base URI by a short prefix (e.g. "gr:" for "http://purl.org/goodrelations/v1#").
  • Entities that represent the user's local data are filled in orange. Entities that are given as external identifiers are filled in grey. Those are mostly enumerated values from GoodRelations.
  • Relationships are labeled with the CURIE of the respective property in the original GoodRelations namespace (black) and in schema.org (red).
  • Literal values are shown as rectangles, labeled with either an example or a short description of the type of value.

The following figure gives an annotated example:

Figure: Conventions for illustrations in the User's Guide

The equivalent Turtle syntax for the example shown in the figure above would be as follows:

foo:Offer a gr:Offering ;
	gr:hasBusinessFunction gr:Sell;
	gr:description "Item text";
	gr:hasPriceSpecification 	[a gr:UnitPriceSpecification ;
						 gr:hasCurrency "USD"].

The same structure in Microdata would look as follows:

<div itemscope itemtype="http://schema.org/Offer" itemid="#Offer">
    <link itemprop="businessFunction" href="http://purl.org/goodrelations/v1#Sell" />
    <span itemprop="description">Item text</span>
    <div itemprop="priceSpecification" itemscope itemtype="http://schema.org/UnitPriceSpecification">
        <span itemprop="priceCurrency">USD</span>
    </div>
</div>

The same structure in RDFa would be as follows:

<div vocab="http://schema.org/"  typeof="Offer" about="#Offer">
    <link rel="businessFunction" href="http://purl.org/goodrelations/v1#Sell" />
    <span property="description">Item text</span>
    <div link="priceSpecification">
        <div typeof="UnitPriceSpecification">
            <span property="priceCurrency">USD</span>
        </div>
    </div>
</div>


Note: The example is incomplete (e.g. it lacks a value for the price) and is just meant for explaining the conventions for illustrations.


Warnings, Tips, and Notes

The following message boxes highlight aspects that require special attention.

Warning

Warning: This is used for highlighting common pitfalls or unintended side-effects


Tip

Tip: This is used for pointing you to information that makes you more efficient or increases the quality of the results.


Note

Note: This is used for providing background information, e.g. the motivation behind a certain modeling decision.