--- a/html-data-guide/index.html Sun Dec 11 21:00:08 2011 +0000
+++ b/html-data-guide/index.html Sun Dec 11 22:16:37 2011 +0000
@@ -372,13 +372,16 @@
<section>
<h6>Mixing Vocabularies using a Type Property</h6>
<p>
- Some <a title="vocabulary">vocabularies</a> may define a <a>property</a> through which <a title="type">types</a> from that vocabulary can be assigned to items that are in a different vocabulary. For example, schema.org could define a <code><a href="http://schema.org/type" class="external free" title="http://schema.org/type" rel="nofollow">http://schema.org/type</a></code> property whose <a>value</a> is a URL, and state that any microdata item that a schema.org <a>type</a> as a value for that property is recognised as being an item of that type. In this case, the types specified in the <code>@itemtype</code> attribute are the <b>primary types</b> of the <a>entity</a> and those specified through the property are the <b>secondary types</b>.
+ Some <a title="vocabulary">vocabularies</a> may define a <a>property</a> through which <a title="type">types</a> from that vocabulary can be assigned to items that are in a different vocabulary. For example, schema.org could define a <code>http://schema.org/type</code> property. It could say that the value of <code>http://schema.org/type</code> must be the URL for a schema.org type. And further, that if the property <code>http://schema.org/type</code> has the value <code>http://schema.org/Person</code>, say, then the item will be interpreted exactly as if the <code>@itemtype</code> attribute held the value <code>http://schema.org/Person</code>.
+ </p>
+ <p class="note">
+ At time of writing schema.org does not specify a <code><a href="http://schema.org/type" rel="nofollow">http://schema.org/type</a></code> property, and this explanation is hypothetical.
</p>
<p>
- Alongside the assertion that <a>property</a> URLs that begin with <code><a href="http://schema.org/" rel="nofollow">http://schema.org/</a></code> have the same semantics as short name properties on items with a schema.org type, this enables the schema.org <a>vocabulary</a> to be mixed in with an item marked up using vEvent:
+ When using this technique, the types specified in the <code>@itemtype</code> attribute are the <b>primary types</b> of the item and those specified through the type property are the <b>secondary types</b>.
</p>
- <p class="note">
- At time of writing schema.org does not specify a <code><a href="http://schema.org/type" rel="nofollow">http://schema.org/type</a></code> property and this example will not work.
+ <p>
+ If the schema.org <a>vocabulary</a> also stated that <a>property</a> URLs that begin with <code>http://schema.org/</code> must be treated in the same way as equivalent short-name properties on items with a schema.org type, the schema.org <a>vocabulary</a> could be mixed in with an item marked up using vEvent:
</p>
<pre><div itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
<strong><link itemprop="http://schema.org/type" href="http://schema.org/Event"></strong>
@@ -408,17 +411,84 @@
<span itemprop="offerCount">1938</span> tickets left
</div></strong>
</div></pre>
- <p>
- Note in particular that the vEvent <code>location</code> <a>property</a> takes text while the schema.org <code>location</code> property takes structured information about the location. These are combined by having an element for the property which requires structured information nested within the property that requires text.
+ <p class="note">
+ The vEvent <code>location</code> <a>property</a> takes text while the schema.org <code>location</code> property takes structured information about the location. These are combined by having an element for the property which requires structured information nested within the property that requires text.
</p>
<p>
- Also note that in this example the <code><a href="http://schema.org/type" class="external free" title="http://schema.org/type" rel="nofollow">http://schema.org/type</a></code> <a>property</a> is only used where necessary, on the <a>entity</a> which needs to be marked as an event in both <a title="vocabulary">vocabularies</a>. Where possible, the schema.org <a>type</a> for an entity is provided explicitly through the <code>@itemtype</code> attribute.
+ This generates the JSON:
+ </p>
+ <pre>{
+ "type": [ "http://microformats.org/profile/hcalendar#vevent" ],
+ "properties": {
+ "http://schema.org/type": [ "http://schema.org/Event" ],
+ "url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "http://schema.org/url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "summary": [ " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ],
+ "http://schema.org/name": [ " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ],
+ "dtstart": [ "2016-04-21T20:00" ],
+ "http://schema.org/startDate": [ "2016-04-21T20:00" ],
+ "location": [ "\n \n \n Wells Fargo Center\n \n \n Philadelphia,\n PA\n \n \n " ],
+ "http://schema.org/location": [{
+ "type": [ "http://schema.org/Place" ],
+ "properties": {
+ "url": [ "http://example.com/wells-fargo-center.html" ],
+ "address": [{
+ "type": [ "http://schema.org/PostalAddress" ],
+ "properties": {
+ "addressLocality": [ "Philadelphia" ],
+ "addressRegion": [ "PA" ]
+ }
+ }]
+ }
+ }],
+ "http://schema.org/offers": [{
+ "type": [ "http://schema.org/AggregateOffer" ],
+ "properties": {
+ "lowPrice": [ "$35" ],
+ "offerCount": [ "1938" ]
+ }
+ }]
+ }
+}</pre>
+ <p>
+ The schema.org consumer would ignore the vEvent vocabulary but recognise the use of the <code>http://schema.org/type</code> property, and therefore treat this data in the same way as if the JSON were:
+ </p>
+ <pre>{
+ "type": [ "http://schema.org/Event" ],
+ "properties": {
+ "url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "name": [ " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ],
+ "startDate": [ "2016-04-21T20:00" ],
+ "location": [{
+ "type": [ "http://schema.org/Place" ],
+ "properties": {
+ "url": [ "http://example.com/wells-fargo-center.html" ],
+ "address": [{
+ "type": [ "http://schema.org/PostalAddress" ],
+ "properties": {
+ "addressLocality": [ "Philadelphia" ],
+ "addressRegion": [ "PA" ]
+ }
+ }]
+ }
+ }],
+ "offers": [{
+ "type": [ "http://schema.org/AggregateOffer" ],
+ "properties": {
+ "lowPrice": [ "$35" ],
+ "offerCount": [ "1938" ]
+ }
+ }]
+ }
+}</pre>
+ <p>
+ Also note that in this example the <code>http://schema.org/type</code> <a>property</a> is only used where necessary, on the item which needs to be marked as an event in both <a title="vocabulary">vocabularies</a>. Where possible, the schema.org <a>type</a> for an entity is provided explicitly through the <code>@itemtype</code> attribute.
</p>
<p>
- This method of mixing <a title="vocabulary">vocabularies</a> requires vocabularies to specify how consumers should recognise items of a particular <a>type</a>. It is recommended that vocabulary authors define an <code>@itemtype</code>-equivalent <a>property</a>, and that, for better integration with RDF tools, this property is <code><a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#type">http://www.w3.org/1999/02/22-rdf-syntax-ns#type</a></code> (TODO: Issue about what to recommend here.)
+ This method of mixing <a title="vocabulary">vocabularies</a> requires vocabularies to specify how consumers should recognise items of a particular <a>type</a>. It is recommended that vocabulary authors define an <code>@itemtype</code>-equivalent <a>property</a>, and that, for better integration with RDF tools, this property is <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</code>.
</p>
<p>
- The other disadvantage of this approach is that there is no support within the microdata API for retrieving items based on the <a>value</a> of a <a>property</a>. In the example above, it would be possible to retrieve the event using:
+ A particular disadvantage of this approach is that there is no support within the microdata API for retrieving items based on the <a>value</a> of a <a>property</a>. In the example above, it would be possible to retrieve the event using:
</p>
<pre>document.getItems('http://microformats.org/profile/hcalendar#vevent')</pre>
<p>
@@ -466,6 +536,47 @@
</div>
</div></pre>
<p>
+ This generates two items:
+ </p>
+ <pre>{
+ "items": [{
+ "type": [ "http://microformats.org/profile/hcalendar#vevent" ],
+ "properties": {
+ "url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "summary": [ "Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1)" ],
+ "dtstart": [ "2016-04-21T20:00" ],
+ "location": [ "Wells Fargo Center, Philadelphia, PA" ]
+ }
+ }, {
+ "type": [ "http://schema.org/Event" ],
+ "properties": {
+ "url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "name": [ " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ],
+ "startDate": [ "2016-04-21T20:00" ],
+ "location": [{
+ "type": [ "http://schema.org/Place" ],
+ "properties": {
+ "url": [ "http://example.com/wells-fargo-center.html" ],
+ "address": [{
+ "type": [ "http://schema.org/PostalAddress" ],
+ "properties": {
+ "addressLocality": [ "Philadelphia" ],
+ "addressRegion": [ "PA" ]
+ }
+ }]
+ }
+ }],
+ "offers": [{
+ "type": [ "http://schema.org/AggregateOffer" ],
+ "properties": {
+ "lowPrice": [ "$35" ],
+ "offerCount": [ "1938" ]
+ }
+ }]
+ }
+ }]
+}</pre>
+ <p>
This method does not require any special <a title="property">properties</a> to be defined in the <a title="vocabulary">vocabularies</a> used to mark up the page, and the two items are directly assigned the relevant <a>type</a> and are thus accessible to scripts through the <code>document.getItems()</code> method.
</p>
<p>
@@ -495,11 +606,12 @@
<span <strong>class="summary" itemprop="summary" property="name"</strong>> Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) </span>
</a>
- <strong><meta itemprop="dtstart" property="startDate" content="2016-04-21T20:00:00"></strong>
- <abbr <strong>class="dtstart" title="2016-04-21T20:00:00"</strong>>
- Thu, 04/21/16
- 8:00 p.m.
- </abbr>
+ <strong><time itemprop="dtstart" property="startDate" content="2016-04-21T20:00:00"></strong>
+ <abbr <strong>class="dtstart" title="2016-04-21T20:00:00"</strong>>
+ Thu, 04/21/16
+ 8:00 p.m.
+ </abbr>
+ </time>
<div <strong>class="location" itemprop="location"
vocab="http://schema.org/" property="location" typeof="Place"</strong>>
@@ -518,46 +630,175 @@
</div>
</div></pre>
<p>
+ A microformats processor will extract the data:
+ </p>
+ <pre>{
+ "type": [ "vevent" ],
+ "properties": {
+ "url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "summary": [ " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ],
+ "dtstart": [ "2016-04-21T20:00:00" ],
+ "location": [ "\n \n \n Wells Fargo Center\n \n \n Philadelphia,\n PA\n \n \n " ]
+ }
+}</pre>
+ <p>
+ A microdata processor will extract something very similar, the only difference being the URL of the type:
+ </p>
+ <pre>{
+ "type": [ "http://microformats.org/profile/hcalendar#vevent" ],
+ "properties": {
+ "url": [ "http://example.com/nba-miami-philidelphia-game3.html" ],
+ "summary": [ " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ],
+ "dtstart": [ "2016-04-21T20:00:00" ],
+ "location": [ "\n \n Wells Fargo Center\n \n \n Philadelphia,\n PA\n \n " ]
+ }
+}</pre>
+ <p>
+ While an RDFa processor will extract the data provided through the schema.org vocabulary:
+ </p>
+ <pre>[] a schema:Event;
+ schema:location [
+ a schema:Place ;
+ schema:address [
+ a schema:PostalAddress ;
+ schema:addressLocality "Philadelphia" ;
+ schema:addressRegion "PA" ;
+ ] ;
+ schema:url <http://example.com/wells-fargo-center.html> ;
+ ] ;
+ schema:name " Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) " ;
+ schema:offers [
+ a schema:AggregateOffer ;
+ schema:lowPrice "$35" ;
+ schema:offerCount "1938" ;
+ ] ;
+ schema:startDate "2016-04-21T20:00:00"^^xsd:dateTime ;
+ schema:url <http://example.com/nba-miami-philidelphia-game3.html> ;
+ .</pre>
+ <p>
It is particularly important to check pages in which <a title="syntax">syntaxes</a> are mixed together using an appropriate validator for each format.
</p>
<p>
The following guidelines may help when creating pages in which different <a title="syntax">syntaxes</a> are mixed together.
</p>
- <ul>
- <li>
- microformats do not use <code>link</code> or <code>meta</code> elements within the content of the page and in some cases require particular elements to be used to encode information, such as using <code>abbr</code> to support the <a href="http://microformats.org/wiki/datetime-design-pattern">datetime-design-pattern</a> as illustrated by the <code>dtstart</code> <a>property</a> in the example above
- </li>
- <li>
- link relations required in certain microformats, particularly XFN, clash with the use of RDFa's <code>@vocab</code> attribute; avoid using <code>@vocab</code> on any ancestor of an element that contains a <code>@rel</code>
- </li>
- <li>
- the following equivalencies between RDFa and microdata attributes generally hold true:
- <ul>
- <li><code>@itemid</code> = <code>@resource</code></li>
- <li><code>@itemtype</code> = <code>@typeof</code> (+ <code>@vocab</code> to enable the use of short names for properties)</li>
- <li><code>@itemprop</code> + <code>@itemscope</code> = <code>@property</code> + an empty <code>@typeof</code> if there's no <code>@itemtype</code></li>
- <li><code>@itemprop</code> otherwise = <code>@property</code></li>
- </ul>
- </li>
- <li>
- when using RDFa, any <a>property</a> elements within an element with a <code>@href</code> will be taken as being properties of the <a>entity</a> identified by the URL in that <code>@href</code>; as long as the link doesn't have a <code>@rel</code>, this can be avoided by adding an empty <code>@property</code> to the link. If the link does have a <code>@rel</code>, you can either move the property elements outside the link or add a <code>@resource</code> attribute whose value is the same as the <code>@resource</code> on the entity element (this can be a local "blank node" identifier in the form <code>_:<var>localName</var></code>
- </li>
- <li>
- RDFa <a title="vocabulary">vocabularies</a> are typically stricter in the range of <a title="value">values</a> that they accept for <a title="property">properties</a> that take dates and times; it is best to use the syntax <code>YYYY-MM-DD</code> for dates, <code>hh:mm:ss</code> for times and <code>YYYY-MM-DDThh:mm:ss</code> for dateTimes to be compliant with the <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">XML Schema dates and times</a> which RDFa-based vocabularies will typically use
- </li>
- <li>
- the <code>@datatype</code> attribute might be required for some RDFa <a title="vocabulary">vocabularies</a>/consumers; others will coerce <a title="value">values</a> into the appropriate datatype based on the <a>property</a> itself. However, if a property takes a structured value, the property element must have <code>datatype="rdf:XMLLiteral"</code> for that structure to be preserved
- </li>
- </ul>
- <p class="issue">
- The guidance above does not adhere to the RDFa 1.1 Lite set of attributes, because of the use of the <code>@resource</code> attribute rather than the <code>@about</code> attribute. However, using <code>@resource</code> gives a more natural mapping when mixing RDFa and microdata within a page. See <a href="http://www.w3.org/2010/02/rdfa/track/issues/119">ISSUE-119</a>.
- </p>
- <p class="issue">
- It is likely that the HTML5 <code>time</code> element will accept types of values that do not have an equivalent XML Schema datatype. These should be avoided when using RDFa. See <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14881">bug 14881</a>.
- </p>
- <p class="issue">
- In (X)HTML5 markup, unprefixed values in the <code>@rel</code> attribute will usually be ignored unless there is a <code>@vocab</code> attribute in scope. In RDFa in XHTML 1.1, some unprefixed values will be recognised as known terms and used to create triples. See <a href="http://www.w3.org/2010/02/rdfa/track/issues/108">ISSUE-108</a>.
- </p>
+
+ <section>
+ <h4>Dates and Times</h4>
+ <p>
+ Microformats do not use <code>link</code> or <code>meta</code> elements within the content of the page and in some cases require particular elements to be used to encode information. In particular, <code>abbr</code> must be used to support the <a href="http://microformats.org/wiki/datetime-design-pattern">datetime-design-pattern</a>. Conversely, properties that hold dates and times must be marked up using the <code>time</code> element in microdata. Using the <code>time</code> element is also advantageous in RDFa, as it automatically confers the appropriate datatype to the value. So when using both microformats and RDFa or microdata, you must nest a <code>time</code> element within a <code>abbr</code> element or vice versa, as shown here:
+ </p>
+ <pre><strong><time itemprop="dtstart" property="startDate" content="2016-04-21T20:00:00"></strong>
+ <abbr <strong>class="dtstart" title="2016-04-21T20:00:00"</strong>>
+ Thu, 04/21/16 8:00 p.m.
+ </abbr>
+ </time></pre>
+ <p>
+ RDFa <a title="vocabulary">vocabularies</a> are typically stricter in the range of <a title="value">values</a> that they accept for <a title="property">properties</a> that take dates and times; it is best to use the syntax <code>YYYY-MM-DD</code> for dates, <code>hh:mm:ss</code> for times and <code>YYYY-MM-DDThh:mm:ss</code> for dateTimes to be compliant with the <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">XML Schema dates and times</a> which RDFa-based vocabularies will typically use.
+ </p>
+ <p class="issue">
+ It is likely that the HTML5 <code>time</code> element will accept types of values that do not have an equivalent XML Schema datatype. These should be avoided when using RDFa. See <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14881">bug 14881</a>.
+ </p>
+ </section>
+
+ <section>
+ <h4>Link relations</h4>
+ <p>
+ Link relations required in certain microformats, particularly XFN, clash with the use of RDFa's <code>@vocab</code> attribute. For example:
+ </p>
+ <pre><a vocab="http://purl.org/dc/terms/"
+ rel="date" href="http://reference.data.gov.uk/id/day/2011-11-15">15th November 2011</a></pre>
+ <p>
+ will result in a <code>dc:date</code> relationship based on RDFa processing, but XFN processing will assume that the link is to someone whom the author of the HTML page is dating. It is best to avoid using <code>@vocab</code> on any ancestor of an element that contains a <code>@rel</code> attribute: use <code>@property</code> instead to provide RDFa properties, and if you need to use <code>@rel</code> attributes on your links, use prefixes instead of <code>@vocab</code> in RDFa.
+ </p>
+ <p class="issue">
+ In (X)HTML5 markup, unprefixed values in the <code>@rel</code> attribute will usually be ignored unless there is a <code>@vocab</code> attribute in scope. In RDFa in XHTML 1.1, some unprefixed values will be recognised as known terms and used to create triples. See <a href="http://www.w3.org/2010/02/rdfa/track/issues/108">ISSUE-108</a>.
+ </p>
+ </section>
+
+ <section>
+ <h4>Microdata and RDFa Equivalencies</h4>
+ <p>
+ When marking up RDFa alongside microdata, the following equivalencies between attributes generally hold true:
+ </p>
+ <ul>
+ <li><code>@itemid</code> = <code>@resource</code></li>
+ <li><code>@itemtype</code> = <code>@typeof</code> (+ <code>@vocab</code> to enable the use of short names for properties)</li>
+ <li><code>@itemprop</code> + <code>@itemscope</code> = <code>@property</code> + an empty <code>@typeof</code> if there's no <code>@itemtype</code></li>
+ <li><code>@itemprop</code> otherwise = <code>@property</code></li>
+ </ul>
+ <p class="issue">
+ The guidance above does not adhere to the RDFa 1.1 Lite set of attributes, because of the use of the <code>@resource</code> attribute rather than the <code>@about</code> attribute. However, using <code>@resource</code> gives a more natural mapping when mixing RDFa and microdata within a page. See <a href="http://www.w3.org/2010/02/rdfa/track/issues/119">ISSUE-119</a>.
+ </p>
+ </section>
+
+ <section>
+ <h4>Properties Within Links</h4>
+ <p>
+ When using RDFa, any <a>property</a> elements within an element with a <code>@href</code> (ie a link) will be taken as being properties of the <a>entity</a> identified by the URL in that <code>@href</code>. This is not the case in microdata or microformats, where the <code>@href</code> attribute is only ever used to provide a value for a property. For example, the microdata:
+ </p>
+ <pre><div itemscope itemtype="http://schema.org/AggregateRating">
+ Ratings:
+ <a href="ratings"
+ title="23,201 IMDb users have given an average vote of 7.2/10">
+ <span itemprop="ratingCount">23,201</span> users</a>
+ </div></pre>
+ <p>
+ will generate an <code>http://schema.org/AggregateRating</code> whose <code>ratingCount</code> is <code>23,201</code>. However, the similar RDFa:
+ </p>
+ <pre><div vocab="http://schema.org/" typeof="AggregateRating">
+ Ratings:
+ <a href="ratings"
+ title="23,201 IMDb users have given an average vote of 7.2/10">
+ <span property="ratingCount">23,201</span> users</a>
+ </div></pre>
+ <p>
+ creates two unconnected statements:
+ </p>
+ <pre>[] a schema:AggregateRating .
+ <http://example.com/ratings> schema:ratingCount "23,201" .</pre>
+ <p>
+ If the link doesn't have a <code>@rel</code> attribute, as in this example, you can avoid the <code>@href</code> attribute creating a new subject by adding an empty <code>@property</code> attribute to the link:
+ </p>
+ <pre><div vocab="http://schema.org/" typeof="AggregateRating">
+ Ratings:
+ <a href="ratings" <strong>property=""</strong>
+ title="23,201 IMDb users have given an average vote of 7.2/10">
+ <span property="ratingCount">23,201</span> users</a>
+ </div></pre>
+ <p>
+ If the link <em>does</em> have a <code>@rel</code> attribute, it is usually easiest to move the relevant property outside the link, for example:
+ </p>
+ <pre><div vocab="http://schema.org/" typeof="AggregateRating">
+ Ratings:
+ <strong><span property="ratingCount" content="23201"></span></strong>
+ <a href="ratings" rel="nofollow"
+ title="23,201 IMDb users have given an average vote of 7.2/10">
+ 23,201 users</a>
+ </div></pre>
+ <p>
+ The alternative is to identify the subject explicitly using a <code>@resource</code> attribute on both the outer element and the link element:
+ </p>
+ <pre><div vocab="http://schema.org/" typeof="AggregateRating"
+ <strong>resource="_:rating"</strong>>
+ Ratings:
+ <a href="ratings" rel="nofollow" <strong>resource="_:rating"</strong>
+ title="23,201 IMDb users have given an average vote of 7.2/10">
+ <span property="ratingCount">23,201</span> users</a>
+ </div></pre>
+ <p>
+ These three methods all generate the same RDF:
+ </p>
+ <pre>[] a schema:AggregateRating ;
+ schema:ratingCount "23,201" ;
+ .</pre>
+ </section>
+
+ <section>
+ <h4>Datatypes</h4>
+ <p>
+ The <code>@datatype</code> attribute might be required for some RDFa <a title="vocabulary">vocabularies</a>/consumers; others will coerce <a title="value">values</a> into the appropriate datatype based on the <a>property</a> itself. However, if a property takes a structured value, the property element must have <code>datatype="rdf:XMLLiteral"</code> for that structure to be preserved.
+ </p>
+ </section>
</section>
</section>