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
+79-69Lines changed: 79 additions & 69 deletions
Original file line number
Diff line number
Diff line change
@@ -87,8 +87,11 @@ <h2>Terminology</h2>
87
87
</dl>
88
88
</section>
89
89
90
+
91
+
90
92
<section>
91
-
<h2>Resource Representation</h2>
93
+
<h2>Data Documents</h2>
94
+
92
95
<section>
93
96
<h3id="use-json">Publish data using developer friendly JSON</h3>
94
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>
@@ -102,6 +105,21 @@ <h3 id="use-json">Publish data using developer friendly JSON</h3>
102
105
</pre>
103
106
</section>
104
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
+
105
123
<section>
106
124
<h3id="use-json-ld">Use well-known identifiers when describing data</h3>
107
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>
136
-
</section>
137
-
138
-
<section>
139
-
<h3id="top-level-object">Use a top-level object</h3>
140
-
<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>
141
-
</section>
142
-
143
-
<section>
144
-
<h3id="native-values">Use native values</h3>
145
-
<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>
146
-
</section>
147
-
148
-
<section>
149
-
<h3id="unordered-values">Assume arrays are unordered</h3>
150
-
<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>
151
-
</section>
152
-
153
151
<section>
154
152
<h3id="typed-objects">Provide one or more types for JSON objects</h3>
155
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>
@@ -213,54 +211,27 @@ <h3 id="use-ids">Identify objects with a unique identifier</h3>
213
211
</section>
214
212
215
213
<section>
216
-
<h3id="dereferencable-entities">Provide a representation of the entity related by URL</h3>
217
-
<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>
218
-
<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>
219
-
</section>
220
-
221
-
<section>
222
-
<h3id="type-links">External references should use typed term</h3>
223
-
<pclass="practicedesc">When using a property intended to reference another entity, properties SHOULD be defined to type string values as being references.</p>
224
-
<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>
238
-
<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>
290
-
<pclass="practicedesc">When describing attributes, entity references SHOULD be used instead of string literals.</p>
291
-
<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>
307
309
</section>
310
+
</section>
311
+
312
+
313
+
<section>
314
+
<h2>Publishing</h2>
308
315
309
316
<section>
310
-
<h3id="reverse-references">When describing an inverse relationship, use a referenced property</h3>
311
-
<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>
312
320
</section>
321
+
</section>
322
+
323
+
<section>
324
+
<h2>Consuming</h2>
313
325
314
-
<!--
315
326
<section>
316
-
<h3 id="xxx"></h3>
317
-
<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