W3C home > Mailing lists > Public > public-vocabs@w3.org > September 2014

Re: Schema.org proposal: New Actions and Actions contigent on an Offer

From: <martin.hepp@ebusiness-unibw.org>
Date: Fri, 19 Sep 2014 11:09:21 +0200
Cc: Vicki Tardif Holland <vtardif@google.com>, W3C Web Schemas Task Force <public-vocabs@w3.org>
Message-Id: <E1DBFAC0-0905-4038-BB55-066AAF757212@ebusiness-unibw.org>
To: ☮ elf Pavlik ☮ <perpetual-tripper@wwelves.org>
Looking at


The main source of confusion is that the proper property for indicating eligible countries is schema:eligibleRegion and not schema:availableAtOrFrom.

All im all, you have the following properties for detailing the terms and conditions of an offer.

1. advanceBookingRequirement
 	The amount of time that is required between accepting the offer and the actual usage of the resource or service.

This is meant for e.g. indicating that you have to book a certain hotel room or flight or service at least seven days before departure etc.

2. availabilityStarts / availabilityEnds 
	The beginning and end of the availability of the product or service included in the offer.

This is mainly meant for rental offers, e.g. for indicating that a vacation home is in general available for rent from March 1 - September 30.
The difference from validFrom/validThrough is that the latter define the validity of the offer, e.g. the period in which you can accept the offer, whereas the former define the period in which you can have the resource.

3. availableAtOrFrom
 	The place(s) from which the offer can be obtained (e.g. store locations).

This is meant for indicating the points of sale, e.g. if a car or boat rental company want to indicate where you can actually get the product. It links an offer to a place, which can e.g. have opening hours.

4. availableDeliveryMethod
 	The delivery method(s) available for this offer.

This is meant for indicating the carriers that the offering party is willing to use for delivery.

5. businessFunction
 	The business function (e.g. sell, lease, repair, dispose) of the offer or component of a bundle (TypeAndQuantityNode). 
	The default is 	http://purl.org/goodrelations/v1#Sell.

This specifies, in a more abstract sense, the bundle of rights that the offering party promises to transfer when you accept the offer.

6. eligibleCustomerType
 	The type(s) of customers for which the given offer is valid.

This is meant to specify e.g. whether your offer is valid for Endusers, resellers, public institutions, etc. See http://schema.org/BusinessEntityType.

7. eligibleDuration
 	The duration for which the given offer is valid.

This is mainly meant for rental offers - if you want to say e.g. that there is a minimum stay of 3 nights, or that you can rent a boat for 1 - 8 hours.

8. eligibleQuantity
 	The interval and unit of measurement of ordering quantities for which the offer or price specification is valid. This allows e.g. specifying that a certain freight charge is valid only for a certain quantity.

This is for indicating e.g. that you have to take a minimum quantity of 2 bottles of wine, or that you cannot get more than 12 bottles per household etc.

Note the difference to the quantities in the TypeAndQuantityNode (via includesObject) - That one specifies how much is included in the offer (e.g. 1,5 kg of wheat), i.e. the quantity to which the price specification refers. With eligibleQuantity, you can say that you have to take at least 3 kg or not more than 12 kg.

9. eligibleRegion
	The ISO 3166-1 (ISO 3166-1 alpha-2) or ISO 3166-2 code, or the GeoShape for the geo-political region(s) for which the offer or delivery charge specification is valid.

This indicates to which region(s) this offer is targeted. GoodRelations does not distinguish between the region of shipment and the residence of the buyer.
So currently, there is only this one property, so the pragmatic definition is "will ship to" for physical goods. For intangible goods, it is typically the region of residence of the buying party.

10. eligibleTransactionVolume
 	The transaction volume, in a monetary unit, for which the offer or price specification is valid, e.g. for indicating a minimal purchasing volume, to express free shipping above a certain order volume, or to limit the acceptance of credit cards to purchases to a certain minimal amount.

Sometimes sellers define how much you must or can buy not in terms of the quantity of the products (see eligibleQuantity), but in terms of a monetary amount. For instance, you can say that the minimum order volume is 20 USD. It is mainly used to express something like "free shipping from USD 29 onwards", when attached to the schema:DeliveryChargeSpecification.

11. priceSpecification
	One or more detailed price specifications, indicating the unit price and delivery or payment charges.

A topic in its own right ;-) Basically all about the compensation expected.

12. validFrom / validThrough
 	The beginning and end of the validity of offer, price specification, or opening hours data.

Note that you can specify validity for the offer (during which interval the offer can be accepted) and the price / price components (for which interval the price is guaranteed to be stable).

There are two properties that may be irritating, because they stem from the pre-GoodRelations ecommerce model in schema.org:

 	The date after which the price is no longer available.

This is from the old pricing model. In the future, it would be better to use a schema:UnitPriceSpecification with schema:validThrough.

	The availability of this item—for example In stock, Out of stock, Pre-order, etc.

In GoodRelations, availability is indicated by defining the inventory level, which is more granular. For an offer including just one item, this can be attached to the schema:Offer via http://schema.org/inventoryLevel.
If the offer includes multiple components (e.g. a bundle - one iPad and two USB sticks), you can indicate the inventory level for each of them by attaching http://schema.org/inventoryLevel to two schema:SomeProducts entities. But even in that case you could say how many bundles you have in stock by attaching http://schema.org/inventoryLevel directly to the schema:Offer.

This is relevant because an offer can be accepted multiple times (e.g. Bestbuy says they sell a certain cable at 5 USD, but you can of course order three cables if you want).

I hope this sheds a bit light on the GoodRelations properties for terms and conditions.


martin hepp
e-business & web science research group
universitaet der bundeswehr muenchen

e-mail:  martin.hepp@unibw.de
phone:   +49-(0)89-6004-4217
fax:     +49-(0)89-6004-4620
www:     http://www.unibw.de/ebusiness/ (group)
         http://www.heppnetz.de/ (personal)
skype:   mfhepp 
twitter: mfhepp

Check out GoodRelations for E-Commerce on the Web of Linked Data!
* Project Main Page: http://purl.org/goodrelations/

On 18 Sep 2014, at 23:44, ☮ elf Pavlik ☮ <perpetual-tripper@wwelves.org> wrote:

> On 09/18/2014 10:43 PM, ☮ elf Pavlik ☮ wrote:
>> On 09/17/2014 11:21 PM, Vicki Tardif Holland wrote:
>>> And adding to Offer
>>> http://schema.org/notAvailableAtOrFrom
>> Whenever we change Offer I think we should check if it also makes sense
>> for Demand. Also looking at name of this property @|@ I would propose
>> considering some alternative solutions before committing to this one. I
>> have some suggestions but would prefer to share them in github PR (or Issue)
> I just suggested another pattern in:
> https://github.com/rvguha/schemaorg/issues/125#issuecomment-56107865
Received on Friday, 19 September 2014 09:09:44 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:29:44 UTC