Hotel examples and documentation must be updated for MTE pattern

[mfhepp]

Unfortunately, the hotels documentation page

http://schema.org/docs/hotels.html

does not properly explain the use of MTEs for hotel rooms as part of offers. Thus, the described approach will not validate with 3.1.

This needs to be fixed, any helping hand is very welcome.

[danbri]

My bad, I thought we'd handled this but I see in retrospect we focussed on the term names and this feel through the net.

Related discussion https://lists.w3.org/Archives/Public/public-schemaorg/2016Aug/0020.html

Recently from @mfhepp :

simply use TWO schema.org types for the object of thr offer in the markup. search for MTE (multi-typed entity) in the discussions. so the hotel room will be both a HotelRoom and a Product at the instance level (instead of at the vocab level)

Let's work out the example here then update docs/hotels.html (and perhaps data/sdo-hotels-examples.txt too).

/cc @RichardWallis

[danbri]

1.) First Offer example:

<div itemscope itemtype="http://schema.org/HotelRoom">
  <span itemprop="name">Single Room</span>
  <span itemprop="description">Our single rooms are cosy and comfortable.</span>
  Rate: <span itemprop="offers" itemscope itemtype="http://schema.org/Offer">
    <link itemprop="businessFunction" href="http://purl.org/goodrelations/v1#LeaseOut" />
    <span itemprop="priceSpecification" itemscope itemtype="http://schema.org/UnitPriceSpecification">
      <meta itemprop="price" content="99.00">$99.00
      <meta itemprop="priceCurrency" content="USD">
      <meta itemprop="unitCode" content="DAY">per night
    </span>
  </span>
</div>

In Microdata, we can add another type (from same vocabulary) as a space separated list of URLs:

<div itemscope itemtype="http://schema.org/HotelRoom http://schema.org/Product">
  <span itemprop="name">Single Room</span>
  <span itemprop="description">Our single rooms are cosy and comfortable.</span>
  Rate: <span itemprop="offers" itemscope itemtype="http://schema.org/Offer">
    <link itemprop="businessFunction" href="http://purl.org/goodrelations/v1#LeaseOut" />
    <span itemprop="priceSpecification" itemscope itemtype="http://schema.org/UnitPriceSpecification">
      <meta itemprop="price" content="99.00">$99.00
      <meta itemprop="priceCurrency" content="USD">
      <meta itemprop="unitCode" content="DAY">per night
    </span>
  </span>
</div>

From https://www.w3.org/TR/2013/NOTE-microdata-20131029/#attr-itemtype

The itemtype attribute, if specified, must have a value that is an unordered set of unique space-separated tokens that are case-sensitive, each of which is a valid URL that is an absolute URL, and all of which are defined to use the same vocabulary.

The item types must all be types defined in applicable specifications and must all be defined to use the same vocabulary.

Note that Microdata is more constraining than RDFa and JSON-LD regarding multiple-types.

2.) Can we show with itemOffered instead?

From doc/hotels.html

The relationship between the offer and the room included in the offer can be represented via either the offers property (from the room to the offer) or via itemsOffered (from the offer to the room).

[danbri]

Aside: I imagine some might make the case that a hotel room is more of a service than a product. I imagine that @RichardWallis might note that this relates to his argument that we should have an Offerable type to stop this distinction being forced especially for not-for-profit scenarios. I also expect @mfhepp to note that Good Relation originally had a ProductOrService type. But for the sake of rapid fix to the Hotel examples, should we used Product or Service for now? /cc @vholland

[danbri]

Here's a JSON-LD conversion of the above (both checked in http://linter.structured-data.org and elsewhere)

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": ["HotelRoom", "Product"],
    "name": "Single Room",
     "description": "Our single rooms are cosy and comfortable.",
      "offers":
        { 
           "@type": "Offer",
           "businessFunction": "http://purl.org/goodrelations/v1#LeaseOut",
            "priceSpecification":
              {
                "@type": "UnitPriceSpecification",
                "price":  "99.00",
                "priceCurrency": "USD",
                "unitCode": "DAY"
              }
        }
}
</script>

Here's RDFa 1.1:

<div vocab="http://schema.org/" typeof="HotelRoom Product">
  <span property="name">Single Room</span>
  <span property="description">Our single rooms are cosy and comfortable.</span>
  Rate: <span property="offers" typeof="Offer">
    <link property="businessFunction" href="http://purl.org/goodrelations/v1#LeaseOut" />
    <span property="priceSpecification" typeof="UnitPriceSpecification">
      <meta property="price" content="99.00">$99.00
      <meta property="priceCurrency" content="USD">
      <meta property="unitCode" content="DAY">per night
    </span>
  </span>
</div>

[danbri]

Also relevant: in 3.1, http://schema.org/docs/datamodel.html#conformance was updated to clarify that it is not always necessary to explicitly list all relevant types of something you're describing:

It is not an error for a schema.org entity description to include properties from several independent types, e.g. something might simultaneously be both a Book and a Product and be usefully described with properties from both types. It is useful but not required for the relevant types to be included in such a description.

[mfhepp]

use Product, pls. Hotel rooms are actually bundles of rights on a) physical objects and b) services, but the business function of temporary access to the physical object is imo the dominant one. This also nicely fits the envisioned usage of the accommodation types for real estate patterns by simply changing the business function value.

---

martin hepp www: http://www.heppnetz.de/ email: mhepp@computer.org

Am 22.08.2016 um 16:52 schrieb Dan Brickley notifications@github.com:

Aside: I imagine some might make the case that a hotel room is more of a service than a product. I imagine that @RichardWallis might note that this relates to his argument that we should have an Offerable type to stop this distinction being forced especially for not-for-profit scenarios. I also expect @mfhepp to note that Good Relation originally had a ProductOrService type. But for the sake of rapid fix to the Hotel examples, should we used Product or Service for now?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[danbri]

@mfhepp thanks. Indeed, that works so long as we always take non-sale businessFunction into account. I'm not entirely comfortable with our "default = sell" (or defaulting at all) but that's a larger architectural debate and I can't see any easy alternative. Product works here.

[RichardWallis]

See PR (#1323) for a first stab at an update to the document.

Thanks @danbri for adding justification to my suggestion for the potential for a new Intangible Type 'OfferableItem' that would help in s situation such as this.

[danbri]

Thanks. @mfhepp, @vholland would you have time to review https://github.com/schemaorg/schemaorg/pull/1323/files ? I'll also take a look.

[RichardWallis]

@mfhepp You may want to redo the diagram yourself - for some reason mine came out a bit clunky and a bit too pink!

[mfhepp]

Here is a better version, based on my original OmniGraffle work. Please replace it in your PR.

[mfhepp]

@danbri re "@mfhepp thanks. Indeed, that works so long as we always take non-sale businessFunction into account. I'm not entirely comfortable with our "default = sell" (or defaulting at all) but that's a larger architectural debate and I can't see any easy alternative. Product works here."

Yes, the "default" way was one of the premature optimizations we introduced in the early stage of schema.org to keep markup simple. GoodRelations never had the notion of a default business function, as far as aI remember.

The cleanest approach will be to

1. Remove the "default" notion from the definition of the property.
2. Encourage that all known validators throw a warning or error if an Offer misses a businessFunction.
3. Update all examples in schema.org and on GBYY (Google-Bing-Yandex-Yahoo) documentation pages.

It will make schema.org much more future-proof for use cases that combine various products and services and is what the GoodRelations model initially suggested based on economic theory, see also

http://wiki.goodrelations-vocabulary.org/Documentation/Conceptual_model

[mfhepp]

ALL: Keep in mind that there are issues with MTEs in Microdata in case the same property ID is defined differently for the two types. This is why we introduced additionalType for Microdata.

In Microdata, properties are AFAIK bound to a single type, not globally defined as in RDF.

This might not be a practical problem with the current schema.org meta-model, but it is a source of potential future problems. So RDFa and JSON-LD are better in this case (which will make teh SW advocats happy).

---

martin hepp http://www.heppnetz.de mhepp@computer.org @mfhepp

On 22 Aug 2016, at 17:04, Dan Brickley notifications@github.com wrote:

Here's a JSON-LD conversion of the above (both checked in http://linter.structured-data.org and elsewhere)

Here's RDFa 1.1:

Single Room Our single rooms are cosy and comfortable. Rate: $99.00 per night

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[danbri]

"In Microdata, properties are AFAIK bound to a single type, not globally defined as in RDF."

Microdata doesn't have a schema language, it is up to the party behind the type definition(s) to say how things work. In schema.org's case we choose to say that properties are drawn from a global namespace, and that their association to types evolves over time (along with the supporting definitions).

[mfhepp]

What I wanted to say is that it is a schema.org design decision that properties are meant to be equivalent across types.

In Microdata, however, this intention is not hard-wired by the Microdata spec and there the decision could be revisited lateron.

So in the Microdata world, the property "name" applied to an entitiy of type http://schema.org/Organization and to another entity of type http://schema.org/Book CAN technically be TWO different properties.

If I read the Microdata-to-RDF spec properly, \ in an RDF world **, it all depends on whether the current vocabulary for the type ends with a slash or does not:

https://www.w3.org/TR/microdata-rdf/#generate-predicate-uri

"Set expandedURI to the URI reference constructed by appending the canonicalized fragment value of name to current vocabulary, separated by a U+0023 NUMBER SIGN character ("#") unless the current vocabularyends with either a U+0023 NUMBER SIGN character ("#") or SOLIDUS U+002F ("/")."

In JSON-LD, this is formally specified in the JSON-LD context at

http://schema.org/docs/jsonldcontext.json.

Note that by virtue of this, only the treatment of properties * in an RDF enviroment * is covered. Not all clients consuming schema.org might care about RDF.

The Microdata vocabulary spec, as far as I understand it, binds property names that are no full URIs to a single type and makes no statement on a "global" definition of a property independent from a type:

https://html.spec.whatwg.org/multipage/microdata.html#selecting-names-when-defining-vocabularies

"Properties whose names are just plain words can only be used within the context of the types for which they are intended; properties named using URLs can be reused in items of any type. "

---

martin hepp http://www.heppnetz.de mhepp@computer.org @mfhepp

On 07 Sep 2016, at 13:08, Dan Brickley notifications@github.com wrote:

"In Microdata, properties are AFAIK bound to a single type, not globally defined as in RDF."

Microdata doesn't have a schema language, it is up to the party behind the type definition(s) to say how things work. In schema.org's case we choose to say that properties are drawn from a global namespace, and that their association to types evolves over time (along with the supporting definitions).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[Lovntola]

In your example you use as part of Hotel and HotelRoom. But offers is not a part of the both types.

[github-actions[bot]]

This issue is being tagged as Stale due to inactivity.