You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: index.html
+76-87Lines changed: 76 additions & 87 deletions
Original file line number
Diff line number
Diff line change
@@ -88,28 +88,10 @@ <h2>Terminology</h2>
88
88
</section>
89
89
90
90
91
-
<section>
92
-
<h2>Authoring</h2>
93
-
94
-
<section>
95
-
<h3>Contexts</h3>
96
-
</section>
97
-
98
-
<section>
99
-
<h3>Data Documents</h3>
100
-
</section>
101
-
</section>
102
-
103
-
<section>
104
-
<h2>Publishing</h2>
105
-
</section>
106
91
107
92
<section>
108
-
<h2>Consuming</h2>
109
-
</section>
93
+
<h2>Data Documents</h2>
110
94
111
-
<section>
112
-
<h2>Resource Representation</h2>
113
95
<section>
114
96
<h3id="use-json">Publish data using developer friendly JSON</h3>
115
97
<pclass="practicedesc">JSON [[json]] is the most popular format for publishing data through APIs; developers like it, it is easy to parse, and it is supported natively in most programming languages.</p>
@@ -123,6 +105,21 @@ <h3 id="use-json">Publish data using developer friendly JSON</h3>
123
105
</pre>
124
106
</section>
125
107
108
+
<section>
109
+
<h3id="top-level-object">Use a top-level object</h3>
110
+
<pclass="practicedesc">JSON documents may be in the form of a object, or an array of objects. For most purposes, developers need a single entry point, so the JSON SHOULD be in the form of a single top-level object</p>
111
+
</section>
112
+
113
+
<section>
114
+
<h3id="native-values">Use native values</h3>
115
+
<pclass="practicedesc">When possible, property values SHOULD use native JSON datatypes such as numbers (<em>integer</em>, <em>decimal</em> and <em>floating point</em>) and booleans (<code>true</code> and <code>false</code>).</p>
116
+
</section>
117
+
118
+
<section>
119
+
<h3id="unordered-values">Assume arrays are unordered</h3>
120
+
<pclass="practicedesc">JSON specifies that the values in an array are ordered, however in many cases arrays are also used for values which are unordered. Unless specified within the <a>JSON-LD Context</a>, multiple array values SHOULD be presumed to be unordered. (See <cite><ahref="http://www.w3.org/TR/json-ld/#lists-and-sets">Lists and Sets</a></cite> in [[JSON-LD]]).</p>
121
+
</section>
122
+
126
123
<section>
127
124
<h3id="use-json-ld">Use well-known identifiers when describing data</h3>
128
125
<pclass="practicedesc">By sticking to basic JSON data expression, and providing a <a>JSON-LD Context</a>, all keys used within a JSON document can have unambigious meaning, as they bind to URLs which describe their meaning.</p>
<pclass="practicedesc">While most use of JSON-LD should not require a client to change the data representation, JSON-LD does allow the use of various algorithms to re-shape a JSON-LD document. These require the use of the <a>JSON-LD Context</a>, which is typically represented using a link to a remote document. Because it is remote, processing time can be severely impacted by the time it takes to retrieve this context. Services providing a <a>JSON-LD Context</a> SHOULD set HTTP cache-control headers to allow liberal caching of such contexts, and clients SHOULD attempt to use a locally cached version of these documents. Typically, libraries used to process JSON-LD documents should do this for you. (See also [[json-ld-best-practice-caching]]).</p>
157
-
</section>
158
-
159
-
<section>
160
-
<h3id="top-level-object">Use a top-level object</h3>
161
-
<pclass="practicedesc">JSON documents may be in the form of a object, or an array of objects. For most purposes, developers need a single entry point, so the JSON SHOULD be in the form of a single top-level object</p>
162
-
</section>
163
-
164
-
<section>
165
-
<h3id="native-values">Use native values</h3>
166
-
<pclass="practicedesc">When possible, property values SHOULD use native JSON datatypes such as numbers (<em>integer</em>, <em>decimal</em> and <em>floating point</em>) and booleans (<code>true</code> and <code>false</code>).</p>
167
-
</section>
168
-
169
-
<section>
170
-
<h3id="unordered-values">Assume arrays are unordered</h3>
171
-
<pclass="practicedesc">JSON specifies that the values in an array are ordered, however in many cases arrays are also used for values which are unordered. Unless specified within the <a>JSON-LD Context</a>, multiple array values SHOULD be presumed to be unordered. (See <cite><ahref="http://www.w3.org/TR/json-ld/#lists-and-sets">Lists and Sets</a></cite> in [[JSON-LD]]).</p>
172
-
</section>
173
-
174
151
<section>
175
152
<h3id="typed-objects">Provide one or more types for JSON objects</h3>
176
153
<pclass="practicedesc">Principles of <a>Linked Data</a> dictate that messages SHOULD be self describing, which includes adding a <code>type</code> to such messages.</p>
@@ -234,54 +211,27 @@ <h3 id="use-ids">Identify objects with a unique identifier</h3>
234
211
</section>
235
212
236
213
<section>
237
-
<h3id="dereferencable-entities">Provide a representation of the entity related by URL</h3>
238
-
<pclass="practicedesc">When dereferencing an entity related via a URL, the location SHOULD provide a representation of that entity. (This practices replicates that described in [[ld-bp]] <cite><ahref="http://www.w3.org/TR/ld-bp/#uri-design-principles">Provide at least one machine-readable representation of the resource identified by the URI</a></cite>)</p>
239
-
<p>Corollaries to this best practice is that Cool URIs don't change [[cooluris]], meaning that URLs describing entities SHOULD be stable and not depend on variable information. Also, the URL used to identify an entity is the best API endpoint of that entity (see also <ahref="#api-versioning" class="sectionRef"></a>).</p>
240
-
</section>
241
-
242
-
<section>
243
-
<h3id="type-links">External references should use typed term</h3>
244
-
<pclass="practicedesc">When using a property intended to reference another entity, properties SHOULD be defined to type string values as being references.</p>
245
-
<p>For example, the <code>schema:image</code> property a Thing to an Image:</p>
<p>This will be interpreted as a reference, rather than a string literal, because (at the time of publication), the schema.org JSON-LD Context defines <code>image</code> to be of type <code>@id</code>:</p>
259
-
<preclass="example" title="schema.org context snippet for image">
<h3id="things-not-strings">Things not strings</h3>
215
+
<pclass="practicedesc">When describing attributes, entity references SHOULD be used instead of string literals.</p>
216
+
<p>In some cases, when describing an attribute of an entity, it is tempting to using string values which have no independent meaning. Such values often are used for well known things. A JSON-LD context can define a term for such values, which allow them to appear as strings within the message, but be associated with specific identifiers. In this case, the property must be defined with type <code>@vocab</code> so that values will be interpreted relative to a vocabulary rather than the file location.</p>
<p>See article in SEO Skeptic [[seo-strings-to-things]] for further elaboration on the advantages of using <em>things</em> instead of <em>strings</em>.</p>
<h3id="things-not-strings">Things not strings</h3>
311
-
<pclass="practicedesc">When describing attributes, entity references SHOULD be used instead of string literals.</p>
312
-
<p>In some cases, when describing an attribute of an entity, it is tempting to using string values which have no independent meaning. Such values often are used for well known things. A JSON-LD context can define a term for such values, which allow them to appear as strings within the message, but be associated with specific identifiers. In this case, the property must be defined with type <code>@vocab</code> so that values will be interpreted relative to a vocabulary rather than the file location.</p>
<h3id="reverse-references">When describing an inverse relationship, use a referenced property</h3>
261
+
<pclass="practicedesc"></p>
262
+
</section>
263
+
</section>
264
+
265
+
<section>
266
+
<h2>Contexts</h2>
267
+
268
+
<section>
269
+
<h3id="type-links">External references should use typed term</h3>
270
+
<pclass="practicedesc">When using a property intended to reference another entity, properties SHOULD be defined to type string values as being references.</p>
271
+
<p>For example, the <code>schema:image</code> property a Thing to an Image:</p>
<p>This will be interpreted as a reference, rather than a string literal, because (at the time of publication), the schema.org JSON-LD Context defines <code>image</code> to be of type <code>@id</code>:</p>
285
+
<preclass="example" title="schema.org context snippet for image">
<p>See article in SEO Skeptic [[seo-strings-to-things]] for further elaboration on the advantages of using <em>things</em> instead of <em>strings</em>.</p>
328
309
</section>
310
+
</section>
311
+
312
+
313
+
<section>
314
+
<h2>Publishing</h2>
329
315
330
316
<section>
331
-
<h3id="reverse-references">When describing an inverse relationship, use a referenced property</h3>
332
-
<pclass="practicedesc"></p>
317
+
<h3id="dereferencable-entities">Provide a representation of the entity related by URL</h3>
318
+
<pclass="practicedesc">When dereferencing an entity related via a URL, the location SHOULD provide a representation of that entity. (This practices replicates that described in [[ld-bp]] <cite><ahref="http://www.w3.org/TR/ld-bp/#uri-design-principles">Provide at least one machine-readable representation of the resource identified by the URI</a></cite>)</p>
319
+
<p>Corollaries to this best practice is that Cool URIs don't change [[cooluris]], meaning that URLs describing entities SHOULD be stable and not depend on variable information. Also, the URL used to identify an entity is the best API endpoint of that entity (see also <ahref="#api-versioning" class="sectionRef"></a>).</p>
333
320
</section>
321
+
</section>
322
+
323
+
<section>
324
+
<h2>Consuming</h2>
334
325
335
-
<!--
336
326
<section>
337
-
<h3 id="xxx"></h3>
338
-
<p class="practicedesc"></p>
327
+
<h3id="cache-context">Cache JSON-LD Contexts</h3>
328
+
<pclass="practicedesc">While most use of JSON-LD should not require a client to change the data representation, JSON-LD does allow the use of various algorithms to re-shape a JSON-LD document. These require the use of the <a>JSON-LD Context</a>, which is typically represented using a link to a remote document. Because it is remote, processing time can be severely impacted by the time it takes to retrieve this context. Services providing a <a>JSON-LD Context</a> SHOULD set HTTP cache-control headers to allow liberal caching of such contexts, and clients SHOULD attempt to use a locally cached version of these documents. Typically, libraries used to process JSON-LD documents should do this for you. (See also [[json-ld-best-practice-caching]]).</p>
0 commit comments