forked from schemaorg/schemaorg
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgs.html
374 lines (282 loc) · 23.7 KB
/
gs.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Getting Started - schema.org</title>
<meta name="description" content="Schema.org is a set of extensible schemas that enables webmasters to embed
structured data on their web pages for use by search engines and other applications." />
<link rel="stylesheet" type="text/css" href="schemaorg.css" />
<!-- ##### Generated insert [CSEScript-start] see scripts/genhtmlinserts.sh ##### -->
<!-- Enable CSE Search -->
<script>
(function() {
var cx = '013516846811604855281:nj5laplixaa'; // Insert your own Custom Search engine ID here
var gcse = document.createElement('script'); gcse.type = 'text/javascript'; gcse.async = true;
gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gcse, s);
})();
</script>
<!-- ##### Generated insert [CSEScript-end] see scripts/genhtmlinserts.sh ##### -->
</head>
<body>
<!-- ##### Generated insert [DOCSHDR-start] see scripts/genhtmlinserts.sh ##### -->
<div id="container">
<div id="intro">
<div id="pageHeader">
<div class="wrapper">
<div id="sitename">
<h1>
<a href="../">schema.org</a>
</h1>
</div>
<div id="cse-search-form" style="width: 400px;">
<div class="gcse-searchbox-only" data-resultsurl="search_results.html"></div>
</div>
</div>
</div>
</div>
</div>
<div id="selectionbar">
<div class="wrapper">
<ul>
<li>
<a href="documents.html" >Documentation</a>
</li>
<li>
<a href="schemas.html" >Schemas</a>
</li>
<li>
<a href="../" >Home</a>
</li>
</ul>
</div>
</div>
<!-- ##### Generated insert [DOCSHDR-end] see scripts/genhtmlinserts.sh ##### -->
<div id="mainContent" class="faq">
<h1>Getting started with schema.org using Microdata</h1>
<p>Most webmasters are familiar with HTML tags on their pages. Usually, HTML tags tell the browser how to display the information included in the tag. For example, <code><h1>Avatar</h1></code> tells the browser to display the text string "Avatar" in a heading 1 format. However, the HTML tag doesn't give any information about what that text string means—"Avatar" could refer to the hugely successful 3D movie, or it could refer to a type of profile picture—and this can make it more difficult for search engines to intelligently display relevant content to a user.</p>
<p>Schema.org provides a collection of shared vocabularies webmasters can use to mark up their pages in ways that can be understood by the major search engines: Google, Microsoft, Yandex and Yahoo!</p>
<p>You use the <a href="../">schema.org</a> vocabulary along with the <a href="http://en.wikipedia.org/wiki/Microdata_(HTML)">Microdata</a>, <a href="http://en.wikipedia.org/wiki/RDFa">RDFa</a>, or
<a href="http://en.wikipedia.org/wiki/JSON-LD">JSON-LD</a> formats to add information to your Web content.
This guide will help get you up to speed with Microdata and schema.org so that you can start adding markup to your web pages.</p>
<p>Although this guide focuses on <a href="http://en.wikipedia.org/wiki/Microdata_(HTML)">Microdata</a>,
most examples on the <a href="/">schema.org</a> site show examples in RDFa and JSON-LD too.
The basic ideas (types, properties etc.) introduced here are relevant beyond Microdata - take a look at the
examples to see how the details compare.</p>
<span id="top"></span>
<ol class="toc">
<li><a href="#microdata_how">How to mark up your content using microdata</a>
<ol class="toc" type="a">
<li><a href="#microdata_why">Why use microdata?</a>
</li>
<li><a href="#microdata_itemscope_itemtype">itemscope and itemtype</a>
</li>
<li><a href="#microdata_itemprop">itemprop</a>
</li>
<li><a href="#microdata_embedded">Embedded items</a>
</li>
</ol>
</li>
<li><a href="#schemaorg">Using the schema.org vocabulary</a>
<ol class="toc" type="a">
<li><a href="#schemaorg_types">schema.org types and properties</a>
</li>
<li><a href="#schemaorg_expected">Expected types, text, and URLs</a>
</li>
<li><a href="#schemaorg_testing">Testing your markup</a>
</li>
</ol>
</li>
<li><a href="#advanced">Advanced topic: Machine-understandable versions of information</a>
<ol class="toc" type="a">
<li><a href="#advanced_dates">Dates, times, and durations</a>
</li>
<li><a href="#advanced_enum">Enumerations and canonical references</a>
</li>
<li><a href="#advanced_missing">Missing/implicit information</a>
</li>
<li><a href="#advanced_extending">Extending schema.org</a>
</li>
</ol>
</li>
</ol>
<h2 id="microdata_how">1. How to mark up your content using microdata</h2>
<h3 id="microdata_why">1a. Why use microdata?</h3>
<p>Your web pages have an underlying meaning that people understand when they read the web pages. But search engines have a limited understanding of what is being discussed on those pages. By adding additional tags to the HTML of your web pages—tags that say, "Hey search engine, this information describes this specific movie, or place, or person, or video"—you can help search engines and other applications better understand your content and display it in a useful, relevant way. Microdata is a set of tags, introduced with HTML5, that allows you to do this.
<h3 id="microdata_itemscope_itemtype">1b. itemscope and itemtype</h3>
<p>Let's start with a concrete example. Imagine you have a page about the movie Avatar—a page with a link to a movie trailer, information about the director, and so on. Your HTML code might look something like this:</p>
<pre>
<div>
<h1>Avatar</h1>
<span>Director: James Cameron (born August 16, 1954)</span>
<span>Science fiction</span>
<a href="../movies/avatar-theatrical-trailer.html">Trailer</a>
</div>
</pre>
<p>To begin, identify the section of the page that is "about" the movie Avatar. To do this, add the itemscope element to the HTML tag that encloses information about the item, like this:</p>
<pre>
<div <strong>itemscope</strong>>
<h1>Avatar</h1>
<span>Director: James Cameron (born August 16, 1954) </span>
<span>Science fiction</span>
<a href="../movies/avatar-theatrical-trailer.html">Trailer</a>
</div>
</pre>
<p>By adding <code>itemscope</code>, you are specifying that the HTML contained in the <code><div>...</div></code> block is about a particular item.</p>
<p>But it's not all that helpful to specify that there is an item being discussed without specifying what kind of an item it is. You can specify the type of item using the <code>itemtype</code> attribute immediately after the <code>itemscope</code>.</p>
<pre><div itemscope <strong>itemtype="http://schema.org/Movie"</strong>>
<h1>Avatar</h1>
<span>Director: James Cameron (born August 16, 1954)</span>
<span>Science fiction</span>
<a href="../movies/avatar-theatrical-trailer.html">Trailer</a>
</div></pre>
<p>This specifies that the item contained in the div is in fact a Movie, as defined in the schema.org type hierarchy. Item types are provided as URLs, in this case <code>http://schema.org/Movie</code>.
<p class="backtotop" style="text-align:right;"><a href="#top">Back to top</a></p>
<h3 id="microdata_itemprop">1c. itemprop</h3>
<p>What additional information can we give search engines about the movie Avatar? Movies have interesting properties such as actors, director, ratings. To label properties of an item, use the <code>itemprop</code> attribute. For example, to identify the director of a movie, add <code>itemprop="director"</code> to the element enclosing the director's name. (There's a full list of all the properties you can associate with a movie at http://schema.org/Movie.)</p>
<pre><div itemscope itemtype ="http://schema.org/Movie">
<h1 <strong>itemprop="name"</strong>>Avatar</h1>
<span>Director: <span <strong>itemprop="director"</strong>>James Cameron</span> (born August 16, 1954)</span>
<span <strong>itemprop="genre"</strong>>Science fiction</span>
<a href="../movies/avatar-theatrical-trailer.html" <strong>itemprop="trailer"</strong>>Trailer</a>
</div></pre>
<p>Note that we have added additional <code><span>...</span></code> tags to attach the <code>itemprop</code> attributes to the appropriate text on the page. <code><span></code> tags don't change the way pages are rendered by a web browser, so they are a convenient HTML element to use with <code>itemprop</code>.</p>
<p>Search engines can now understand not just that http://www.avatarmovie.com is a URL, but also that it's the URL for the trailer for the science-fiction movie Avatar, which was directed by James Cameron.</p>
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="microdata_embedded">1d. Embedded items</h3>
<p>Sometimes the value of an item property can itself be another item with its own set of properties. For example, we can specify that the director of the movie is an item of type Person and the Person has the properties <code>name</code> and <code>birthDate</code>. To specify that the value of a property is another item, you begin a new <code>itemscope</code> immediately after the corresponding <code>itemprop</code>.</p>
<pre><div itemscope itemtype ="http://schema.org/Movie">
<h1 itemprop="name">Avatar</h1>
<div <strong>itemprop="director" itemscope itemtype="http://schema.org/Person"</strong>>
Director: <span itemprop="name">James Cameron</span> (born <span <strong>itemprop="birthDate"</strong>>August 16, 1954</span>)
</div>
<span itemprop="genre">Science fiction</span>
<a href="../movies/avatar-theatrical-trailer.html" itemprop="trailer">Trailer</a>
</div></pre>
<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="schemaorg">2. Using the schema.org vocabulary</h2>
<h3 id="schemaorg_types">2a. schema.org types and properties</h3>
<p>Not all web pages are about movies and people—in addition to the Movie and Person types described in section 1, schema.org describes a variety of other item types, each of which has its own set of properties that can be used to describe the item.</p>
<p>The broadest item type is <a href="../Thing">Thing</a>, which has four properties: <code>name</code>, <code>description</code>, <code>url</code>, and <code>image</code>. More specific types share properties with broader types. For example, a <a href="../Place">Place</a> is a more specific type of Thing, and a <a href="../LocalBusiness">LocalBusiness</a> is a more specific type of Place. More specific items inherit the properties of their parent. (Actually, a LocalBusiness is a more specific type of Place <i>and</i> a more specific type of Organization, so it inherits properties from both parent types.)</p>
<p>Here's a set of commonly used item types:</p>
<ul>
<li>Creative works: <a href="../CreativeWork">CreativeWork</a>, <a href="../Book">Book</a>, <a href="../Movie">Movie</a>, <a href="../MusicRecording">MusicRecording</a>, <a href="../Recipe">Recipe</a>, <a href="../TVSeries">TVSeries</a> ...</li>
<li>Embedded non-text objects: <a href="../AudioObject">AudioObject</a>, <a href="../ImageObject">ImageObject</a>, <a href="../VideoObject">VideoObject</a></li>
<li><a href="../Event">Event</a></li>
<li><a href="../Organization">Organization</a></li>
<li><a href="../Person">Person</a></li>
<li><a href="../Place">Place</a>, <a href="../LocalBusiness">LocalBusiness</a>, <a href="../Restaurant">Restaurant</a> ...</li>
<li><a href="../Product">Product</a>, <a href="../Offer">Offer</a>, <a href="../AggregateOffer">AggregateOffer</a></li>
<li><a href="../Review">Review</a>, <a href="../AggregateRating">AggregateRating</a></li>
</ul>
<p>You can also see a <a href="full.html">full list of all item types</a>, listed on a single page.
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="schemaorg_expected">2b. Expected types, text, and URLs</h3>
<p>Here are a few notes to keep in mind when adding schema.org markup to your web pages.</p>
<ul>
<li><strong>More is better, except for hidden text.</strong> In general, the more content you mark up, the better. However, as a general rule, you should mark up only the content that is visible to people who visit the web page and not content in hidden div's or other hidden page elements.</li>
<li><strong>Expected types vs text.</strong> When browsing the schema.org types, you will notice that many properties have "expected types". This means that the value of the property can itself be an embedded item (see section 1d: embedded items). But this is not a requirement—it's fine to include just regular text or a URL. In addition, whenever an expected type is specified, it is also fine to embed an item that is a child type of the expected type. For example, if the expected type is Place, it's also OK to embed a LocalBusiness.</li>
<li><strong>Using the url property.</strong> Some web pages are about a specific item. For example, you may have a web page about a single person, which you could mark up using the Person item type. Other pages have a collection of items described on them. For example, your company site could have a page listing employees, with a link to a profile page for each person. For pages like this with a collection of items, you should mark up each item separately (in this case as a series of Persons) and add the url property to the link to the corresponding page for each item, like this:
<pre>
<div itemscope itemtype="http://schema.org/Person">
<a href="alice.html" <strong>itemprop="url"</strong>>Alice Jones</a>
</div>
<div itemscope itemtype="http://schema.org/Person">
<a href="bob.html" <strong>itemprop="url"</strong>>Bob Smith</a>
</div>
</pre>
</li>
</ul>
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="schemaorg_testing">2c. Testing your markup</h3>
<p>Much like a web browser is important for testing changes to your web page layout, and a code compiler is important for testing code you write, you should also test your schema.org markup to make sure it is implemented correctly. Google provides a rich snippets testing tool, which you can use to test your markup and identify any errors.</p>
<h2 id="advanced">3. Advanced topic: Machine-understandable versions of information</h2>
<p>Many pages can be described using only the <code>itemscope</code>, <code>itemtype</code>, and <code>itemprop</code> attributes (described in section 1) along with the types and properties defined on schema.org (described in section 2). </p>
<p>However, sometimes an item property is difficult for a machine to understand without additional disambiguation. This section describes how you can provide machine-understandable versions of information when marking up your pages.</p>
<ul>
<li>Dates, times, and durations: use the <code>time</code> tag with <code>datetime</code></li>
<li>Enumerations and canonical references: use the <code>link</code> tag with <code>href</code></li>
<li>Missing/implicit information: use the <code>meta</code> tag with <code>content</code>.</li>
</ul>
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="advanced_dates">3a. Dates, times, and durations: use the time tag with datetime</h3>
<p>Dates and times can be difficult for machines to understand. Consider the date "04/01/11". Does it mean January 11, 2004? January 4, 2011? Or April 1, 2011? To make dates unambiguous, use the <code>time</code> tag along with the <code>datetime</code> attribute. The value of the <code>datetime</code> attribute is the date specified using <code>YYYY-MM-DD</code> format. The HTML code below specifies the date unambiguously as April 1, 2011. </p>
<pre><strong><time datetime="2011-04-01"></strong>04/01/11<strong></time></strong></pre>
<p>You can also specify a time within a day, using the <code>hh:mm</code> or <code>hh:mm:ss</code> format. Times are prefixed with the letter <code>T</code> and can be provided along with a date, like this:</p>
<pre><strong><time datetime="2011-05-08T19:30"></strong>May 8, 7:30pm<strong></time></strong></pre>
<p>Let's see this in context. Here's some HTML describing a concert taking place on May 8, 2011. The Event markup includes the name of the event, a description, and the date of the event.</p>
<pre><div <strong>itemscope itemtype="http://schema.org/Event"</strong>>
<div <strong>itemprop="name"</strong>>Spinal Tap</div>
<span <strong>itemprop="description"</strong>>One of the loudest bands ever
reunites for an unforgettable two-day show.</span>
Event date:
<strong><time itemprop="startDate" datetime="2011-05-08T19:30"></strong>May 8, 7:30pm<strong></time></strong>
</div></pre>
<p>Durations can be specified in an analogous way using the <code>time</code> tag with the <code>datetime</code> attribute. Durations are prefixed with the letter <code>P</code> (stands for "period"). Here's how you can specify a recipe cook time of 1 ½ hours:</p>
<pre><strong><time</strong> itemprop="cookTime" <strong>datetime="PT1H30M"</strong>>1 1/2 hrs<strong></time></strong></pre>
<p><code>H</code> is used to designate the number of hours, and <code>M</code> is used to designate the number of minutes.</p>
<p>The date, time, and duration standards are specified by the <a href="http://en.wikipedia.org/wiki/ISO_8601" target="new">ISO 8601 date/time standard</a>.
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="advanced_enum">3b. Enumerations and canonical references: use link with href</h3>
<h4 id="advanced_enum_enum">Enumerations</h4>
<p>Some properties can take only a limited set of possible values. Programmers often call these "enumerations." For example, an online store with an item for sale could use the <a href="http://schema.org/Offer">Offer</a> item type to specify the details of the offer. The <code>availability</code> property can typically have one of only a few possible values—<code>In stock</code>, <code>Out of stock</code>, <code>Pre-order</code>, and so on. Much like item types are specified as URLs, possible values for an enumeration on schema.org can also be specified as URLs.</p>
<p>Here is an item for sale, marked up with the Offer type and relevant properties:</p>
<pre>
<div itemscope itemtype="http://schema.org/Offer">
<span itemprop="name">Blend-O-Matic</span>
<span itemprop="price">$19.95</span>
<span itemprop="availability">Available today!</span>
</div></pre>
<p>And here is the same item, but using <code>link</code> and <code>href</code> to unambiguously specify the availability as one of the permitted values:</p>
<pre><div itemscope itemtype="http://schema.org/Offer">
<span itemprop="name">Blend-O-Matic</span>
<span itemprop="price">$19.95</span>
<strong><link itemprop="availability" href="http://schema.org/InStock"/></strong>Available today!
</div></pre>
<p>Schema.org provides enumerations for a handful of properties—typically wherever there are a limited number of typical values for a property, there is a corresponding enumeration specified in schema.org. In this case, the possible values for <code>availability</code> are specified in <a href="http://schema.org/ItemAvailability">ItemAvailability</a>.</p>
<h4 id="advanced_canonical">Canonical references</h4>
<p>Typically, links are specified using the <code><a></code> element. For example, the following HTML links to the Wikipedia page for the book Catcher in the Rye.</p>
<pre><div itemscope itemtype="http://schema.org/Book">
<span itemprop="name">The Catcher in the Rye</span>—
by <span itemprop="author">J.D. Salinger</span>
Here is the book's <a <strong>itemprop="url"</strong> href="http://en.wikipedia.org/wiki/The_Catcher_in_the_Rye">Wikipedia page</a>.
</div></pre>
<p>As you can see, <code>itemprop="url"</code> can be used to specify a link to a page on another site (in this case Wikipedia) discussing the same item. Links to 3rd party sites can help search engines to better understand the item you are describing on your web page.</p>
<p>However, you might not want to add a visible link on your page. In this case, you can use a <code>link</code> element instead, as follows:</p>
<pre><div itemscope itemtype="http://schema.org/Book">
<span itemprop="name">The Catcher in the Rye</span>—
<strong><link itemprop="url" href="http://en.wikipedia.org/wiki/The_Catcher_in_the_Rye" /></strong>
by <span itemprop="author">J.D. Salinger</span>
</div></pre>
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="advanced_missing">3c. Missing/implicit information: use the meta tag with content</h3>
<p>Sometimes, a web page has information that would be valuable to mark up, but the information can't be marked up because of the way it appears on the page. The information may be conveyed in an image (for example, an image used to represent a rating of 4 out of 5) or a Flash object (for example, the duration of a video clip), or it may be implied but not stated explicitly on the page (for example, the currency of a price).</p>
<p>In these cases, use the <code>meta</code> tag along with the <code>content</code> attribute to specify the information. Consider this example—the image shows users a 4 out of 5 star rating:</p>
<pre><div itemscope itemtype="http://schema.org/Offer">
<span itemprop="name">Blend-O-Matic</span>
<span itemprop="price">$19.95</span>
<img src="four-stars.jpg" />
Based on 25 user ratings
</div></pre>
<p>Here is the example again with the rating information marked up.</p>
<pre><div itemscope itemtype="http://schema.org/Offer">
<span itemprop="name">Blend-O-Matic</span>
<span itemprop="price">$19.95</span>
<div <strong>itemprop="reviews" itemscope itemtype="http://schema.org/AggregateRating"</strong>>
<img src="four-stars.jpg" />
<strong><meta itemprop="ratingValue" content="4" /></strong>
<strong><meta itemprop="bestRating" content="5" /></strong>
Based on <span <strong>itemprop="ratingCount"</strong>>25</span> user ratings
</div>
</div></pre>
<p>This technique should be used sparingly. Only use <code>meta</code> with content for information that cannot otherwise be marked up.</p>
<p class="backtotop"><a href="#top">Back to top</a></p>
<h3 id="advanced_extending">3d. Extending schema.org</h3>
<p>Most sites and organizations will not have a reason to extend schema.org. However, schema.org offers the ability to specify additional properties or sub-types to existing types. If you are interested in doing this, read more about the <a href="http://schema.org/docs/extension.html">schema.org extension mechanism</a>. </p>
<br /><br /><br />
</div>
<div id="footer"><p>
<a href="../docs/terms.html">Terms and conditions</a></p>
</div>
</body>
</html>