--- a/html-data-guide/index.html Wed Dec 21 12:17:15 2011 +0000
+++ b/html-data-guide/index.html Wed Dec 21 16:26:57 2011 +0000
@@ -353,209 +353,20 @@
<a title="property">Properties</a> in microdata are either short names (in which case they are scoped to the <a>vocabulary</a> of the <a title="type">types</a> of the entity) or URLs. A URL property has no relationship to a given short name property unless that relationship is specified within the vocabulary that defines the properties.
</p>
<p>
- You might find that you need to target two consumers who each recognise items using <a title="type">types</a> from different <a title="vocabularies">vocabularies</a>. For example, you might want to both target schema.org and use the vEvent vocabulary with the original HTML:
+ You might find that you need to target two consumers who each recognise items using <a title="type">types</a> from different <a title="vocabularies">vocabularies</a>. For example, you might want to both target schema.org and use the vEvent vocabulary when providing data about an event.
</p>
- <pre><a href="nba-miami-philadelphia-game3.html">
-NBA Eastern Conference First Round Playoff Tickets:
- Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1)
-</a>
-
-Thu, 04/21/16
-8:00 p.m.
-
-<a href="wells-fargo-center.html">
-Wells Fargo Center
-</a>
-Philadelphia, PA</pre>
<p>
In this case there are three options available to you. The first, if consumers support it, is to use a different <a>syntax</a> for one of the <a title="vocabulary">vocabularies</a>. For example, the vEvent vocabulary is only supported in microdata but schema.org can be consumed from either microdata or RDFa, so it would be possible to mark up the data using the vEvent vocabulary in microdata and the schema.org vocabulary in RDFa. This approach is described in more detail in <a href="#mixing-syntaxes" class="sectionRef"></a>. Mixing syntaxes within a single page is rarely a good option but in some circumstances it may be preferable to the other workarounds described here.
</p>
<p>
- The other options for marking up using multiple vocabularies in microdata are described below.
+ The second option is to use a <a>property</a> that is treated by consumers as providing the <a>type</a> for an item, as if the <code>@itemtype</code> attribute had been used. This requires <a>vocabulary</a> authors to define such a property for a given vocabulary.
</p>
- <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>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>
- 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>
- 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>
- <a itemprop="url <strong>http://schema.org/url</strong>" href="nba-miami-philadelphia-game3.html">
- NBA Eastern Conference First Round Playoff Tickets:
- <span itemprop="summary <strong>http://schema.org/name</strong>"> Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) </span>
- </a>
-
- <meta itemprop="dtstart <strong>http://schema.org/startDate</strong>" content="2016-04-21T20:00">
- Thu, 04/21/16
- 8:00 p.m.
-
- <div itemprop="location">
- <strong><div itemprop="http://schema.org/location" itemscope itemtype="http://schema.org/Place">
- <a itemprop="url" href="wells-fargo-center.html">
- Wells Fargo Center
- </a>
- <div itemprop="address" itemscope itemtype="http://schema.org/PostalAddress">
- <span itemprop="addressLocality">Philadelphia</span>,
- <span itemprop="addressRegion">PA</span>
- </div>
- </div></strong>
- </div>
-</div></pre>
- <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>
- 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-philadelphia-game3.html" ],
- "http://schema.org/url": [ "http://example.com/nba-miami-philadelphia-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" ]
- }
- }]
- }
- }]
- }
-}</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-philadelphia-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" ]
- }
- }]
- }
- }]
- }
-}</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>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</code>.
- </p>
- <p>
- 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>
- but not through:
- </p>
- <pre>document.getItems('http://schema.org/Event')</pre>
- <p>
- Scripts that extract microdata information using the DOM will be faster if they can use the primary <a title="type">types</a> for an item, specified within the <code>@itemtype</code> attribute, so you should specify types accessed through scripts within <code>@itemtype</code> rather than through a <a>property</a> wherever possible.
- </p>
- </section>
- <section>
- <h6>Mixing Vocabularies using Repeated Content</h6>
- <p>
- The second method of supporting multiple <a title="property">properties</a> is to have the <a>entity</a> represented by two (or more) microdata items on the page. To enable dragging and dropping the data from these items, they should be nested inside each other. Properties can be set on the outer element using <code>link</code> and <code>meta</code> elements which are hidden from users, while the visible content of the page is marked up by the inner element.
- </p>
- <pre><div itemscope itemtype="<strong>http://microformats.org/profile/hcalendar#vevent</strong>">
- <strong><link itemprop="url" href="nba-miami-philadelphia-game3.html">
- <meta itemprop="summary" content="Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1)">
- <meta itemprop="dtstart" content="2016-04-21T20:00">
- <meta itemprop="location" content="Wells Fargo Center, Philadelphia, PA"></strong>
- <div itemscope itemtype="<strong>http://schema.org/Event</strong>">
- <a itemprop="url" href="nba-miami-philadelphia-game3.html">
- NBA Eastern Conference First Round Playoff Tickets:
- <span itemprop="name"> Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) </span>
- </a>
-
- <meta itemprop="startDate" content="2016-04-21T20:00">
- Thu, 04/21/16
- 8:00 p.m.
-
- <div itemprop="location" itemscope itemtype="http://schema.org/Place">
- <a itemprop="url" href="wells-fargo-center.html">
- Wells Fargo Center
- </a>
- <div itemprop="address" itemscope itemtype="http://schema.org/PostalAddress">
- <span itemprop="addressLocality">Philadelphia</span>,
- <span itemprop="addressRegion">PA</span>
- </div>
- </div>
- </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-philadelphia-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-philadelphia-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" ]
- }
- }]
- }
- }]
- }
- }]
-}</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>
- The disadvantages of this method are that the page contains more items than there are <a title="entity">entities</a> (in the above example, two items representing the same event), and it requires repetition of data within the page.
- </p>
- </section>
+ <p>
+ The third option is to repeat the data markup, once in visible content and once in hidden markup (either through <code>link</code> and <code>meta</code> elements or in a section hidden using CSS).
+ </p>
+ <p>
+ These two options are described in detail within <a href="#multiple-types-microdata" class="sectionRef"></a>.
+ </p>
</section>
</section>
<section id="mixing-syntaxes">
@@ -1228,5 +1039,207 @@
Many thanks to the members of the HTML Data Task Force for their contributions to this document.
</p>
</section>
+
+ <section class="appendix" id="multiple-types-microdata">
+ <h2>Multiple Item Types in Microdata</h2>
+ <p>
+ As discussed in <a class="sectionRef" href="#mixing-vocabularies-microdata"></a>, microdata does not support providing multiple <a title="type">types</a> from different <a title="vocabulary">vocabularies</a> to a given item within the <code>@itemtype</code> attribute. There are two work-arounds for this, which are discussed here using the example of targetting both schema.org and use the vEvent vocabulary with the original HTML:
+ </p>
+ <pre><a href="nba-miami-philadelphia-game3.html">
+ NBA Eastern Conference First Round Playoff Tickets:
+ Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1)
+</a>
+
+Thu, 04/21/16
+8:00 p.m.
+
+<a href="wells-fargo-center.html">
+ Wells Fargo Center
+</a>
+Philadelphia, PA</pre>
+ <section>
+ <h3>Mixing Vocabularies using a Type Property</h3>
+ <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>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>
+ 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>
+ 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>
+ <a itemprop="url <strong>http://schema.org/url</strong>" href="nba-miami-philadelphia-game3.html">
+ NBA Eastern Conference First Round Playoff Tickets:
+ <span itemprop="summary <strong>http://schema.org/name</strong>"> Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) </span>
+ </a>
+
+ <meta itemprop="dtstart <strong>http://schema.org/startDate</strong>" content="2016-04-21T20:00">
+ Thu, 04/21/16
+ 8:00 p.m.
+
+ <div itemprop="location">
+ <strong><div itemprop="http://schema.org/location" itemscope itemtype="http://schema.org/Place">
+ <a itemprop="url" href="wells-fargo-center.html">
+ Wells Fargo Center
+ </a>
+ <div itemprop="address" itemscope itemtype="http://schema.org/PostalAddress">
+ <span itemprop="addressLocality">Philadelphia</span>,
+ <span itemprop="addressRegion">PA</span>
+ </div>
+ </div></strong>
+ </div>
+</div></pre>
+ <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>
+ 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-philadelphia-game3.html" ],
+ "http://schema.org/url": [ "http://example.com/nba-miami-philadelphia-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" ]
+ }
+ }]
+ }
+ }]
+ }
+}</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-philadelphia-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" ]
+ }
+ }]
+ }
+ }]
+ }
+}</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>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</code>.
+ </p>
+ <p>
+ 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>
+ but not through:
+ </p>
+ <pre>document.getItems('http://schema.org/Event')</pre>
+ <p>
+ Scripts that extract microdata information using the DOM will be faster if they can use the primary <a title="type">types</a> for an item, specified within the <code>@itemtype</code> attribute, so you should specify types accessed through scripts within <code>@itemtype</code> rather than through a <a>property</a> wherever possible.
+ </p>
+ </section>
+ <section>
+ <h3>Mixing Vocabularies using Repeated Content</h3>
+ <p>
+ The second method of supporting multiple <a title="property">properties</a> is to have the <a>entity</a> represented by two (or more) microdata items on the page. To enable dragging and dropping the data from these items, they should be nested inside each other. Properties can be set on the outer element using <code>link</code> and <code>meta</code> elements which are hidden from users, while the visible content of the page is marked up by the inner element.
+ </p>
+ <pre><div itemscope itemtype="<strong>http://microformats.org/profile/hcalendar#vevent</strong>">
+ <strong><link itemprop="url" href="nba-miami-philadelphia-game3.html">
+ <meta itemprop="summary" content="Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1)">
+ <meta itemprop="dtstart" content="2016-04-21T20:00">
+ <meta itemprop="location" content="Wells Fargo Center, Philadelphia, PA"></strong>
+ <div itemscope itemtype="<strong>http://schema.org/Event</strong>">
+ <a itemprop="url" href="nba-miami-philadelphia-game3.html">
+ NBA Eastern Conference First Round Playoff Tickets:
+ <span itemprop="name"> Miami Heat at Philadelphia 76ers - Game 3 (Home Game 1) </span>
+ </a>
+
+ <meta itemprop="startDate" content="2016-04-21T20:00">
+ Thu, 04/21/16
+ 8:00 p.m.
+
+ <div itemprop="location" itemscope itemtype="http://schema.org/Place">
+ <a itemprop="url" href="wells-fargo-center.html">
+ Wells Fargo Center
+ </a>
+ <div itemprop="address" itemscope itemtype="http://schema.org/PostalAddress">
+ <span itemprop="addressLocality">Philadelphia</span>,
+ <span itemprop="addressRegion">PA</span>
+ </div>
+ </div>
+ </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-philadelphia-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-philadelphia-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" ]
+ }
+ }]
+ }
+ }]
+ }
+ }]
+}</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>
+ The disadvantages of this method are that the page contains more items than there are <a title="entity">entities</a> (in the above example, two items representing the same event), and it requires repetition of data within the page.
+ </p>
+ </section>
+ </section>
</body>
</html>