Implement Best Practices section

.gitignore

@@ -0,0 +1,3 @@
+# JetBrains IDEs
+/.idea/
+/web/

Makefile

@@ -0,0 +1,14 @@
+.PHONY: install
+install:
+	npm install -g respec
+
+
+.PHONY: spec
+spec:
+	respec --verbose --localhost --src spec/index.html --out web/index.html
+
+
+.PHONY: serve
+.ONESHELL: serve
+serve:
+	python -m http.server --directory web 1234

spec/code/context.json

@@ -0,0 +1,26 @@
+{
+  "@context": {
+    "$base": "@base",
+    "$container": "@container",
+    "$direction": "@direction",
+    "$graph": "@graph",
+    "$id": "@id",
+    "$import": "@import",
+    "$included": "@included",
+    "$index": "@index",
+    "$json": "@json",
+    "$language": "@language",
+    "$list": "@list",
+    "$nest": "@nest",
+    "$none": "@none",
+    "$prefix": "@prefix",
+    "$propagate": "@propagate",
+    "$protected": "@protected",
+    "$reverse": "@reverse",
+    "$set": "@set",
+    "$type": "@type",
+    "$value": "@value",
+    "$version": "@version",
+    "$vocab": "@vocab"
+  }
+}

spec/code/with-convenience-context.yaml

@@ -0,0 +1,13 @@
+"@context":
+  - https://prefix.cc/context
+  - https://yaml-ld.dev/context
+  - ex: https://example.org/
+    name:
+      $id: rdfs:label
+      $container: $language
+$id: ex:Ray
+$type: ex:Cat
+name:
+  en: Ray
+  ua: Промiнчик
+  ru: Лучик

spec/code/without-convenience-context.yaml

@@ -0,0 +1,12 @@
+"@context":
+  - https://prefix.cc/context
+  - ex: https://example.org/
+    name:
+      "@id": rdfs:label
+      "@container": "@language"
+"@id": ex:Ray
+"@type": ex:Cat
+name:
+  en: Ray
+  ua: Промiнчик
+  ru: Лучик

spec/index.html

@@ -32,6 +32,23 @@
           "Eemeli Aro"
         ]
       },
+
+      "json-ld-bp": {
+        title: "JSON-LD Best Practices",
+        href: "https://w3c.github.io/json-ld-bp/",
+        publisher: "W3C",
+        date: "2022-05-24",
+        status: "W3C Group Note",
+        authors: [
+          "Gregg Kellogg",
+          "Ivan Herman",
+          "BigBlueHat",
+          "A. Soroka",
+          "Ruben Taelman",
+          "David I. Lehn",
+          "Philippe Le Hegaret",
+        ],
+      },
     },
 
     // Cross-reference definitions
@@ -423,5 +440,98 @@ <h3>Examples</h3>
     </section>
   </section>
 
+    <section id="best-practices" class="informative">
+      <h2>Best Practices</h2>
+
+      <p>Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two
+        useful thoughts.</p>
+
+       <div class="practice">
+          <p class="practicedesc">
+            <span id="use-json-ld-best-practices" class="practicelab">Follow JSON-LD best practices</span>
+            …in order to achieve a greater level of reusability, performance, and human friendliness of YAML-LD aware
+            systems. The [[json-ld-bp]] document is relevant to YAML-LD no less than it is to [[JSON-LD]].
+          </p>
+       </div>
+
+      <div class="practice">
+        <p class="practicedesc">
+          <span id="prebuilt-contexts" class="practicelab">Do not force users to author contexts</span>
+
+          Instead, provide pre-built contexts that the user can reference by URL for majority of common use cases.
+        </p>
+      </div>
+
+      <p>YAML-LD is intended to simplify authoring of Linked Data for a wide range of domain experts: its target
+        audience is not comprised solely of IT professionals. YAML is chosen as a medium to minimize syntactic noise,
+        to keep the authored documents concise and clear. [[JSON-LD]] (and hence YAML-LD) Context comprises a special
+        language of its own. A requirement to <i>author</i> such a context would make the domain expert's job much
+        harder, — which we, as system architects and developers, should try to avoid.</p>
+
+      <div class="practice">
+        <p class="practicedesc">
+          <span id="conceal-contexts" class="practicelab">Use a default context</span>
+        </p>
+
+        If most, or all, of a user's documents are based on one particular context, try to make it the default in order
+        to rescue the user from copy-pasting the same technical incantation from one document to another.
+      </div>
+
+      <p>For instance, according to [[json-ld-api]], the `expand()` method of a JSON-LD processor accepts an
+        `expandContext` argument which can be used to provide a default system context.</p>
+
+      <div class="practice">
+        <p class="practicedesc">
+          <span id="alias-keywords" class="practicelab">Alias JSON-LD keywords</span>
+
+          If possible, map JSON-LD keywords containing the `@` character to keywords that do not contain it.
+        </p>
+      </div>
+
+      <p>The `@` character is reserved as per [[YAML]] specification and thus requires quoting, as in the following
+        example:</p>
+
+      <aside class="example" data-transform="updateExample"
+             title="Example YAML-LD document without Convenience Context">
+        <pre class="yaml" data-include="code/without-convenience-context.yaml" data-include-format="text"></pre>
+      </aside>
+
+      <p>The need to quote these keywords has to be learnt, and introduces one more little irregularity to the document
+        author's life. Besides, on most keyboard layouts typing quotes will require `Shift` — which albeit slightly but
+        does reduce typing speed.</p>
+
+      <p>In order to avoid this, the context might introduce custom mappings for the necessary keywords. For instance,
+        [[schema-org]] context redefines `@id` as just `id` — which seems to be much more convenient to type, and
+        no more difficult to remember.</p>
+
+       <div class="practice">
+          <p class="practicedesc">
+            <span id="convenience-context" class="practicelab">Use YAML-LD Convenience Context</span>
+            <p>YAML-LD users may use a JSON-LD context provided as part of this specification, henceforth known as the
+         <dfn>convenience
+          context</dfn>, which defines a standardized mapping of every `@`-keyword to a `$`-keyword, except `@context`.
+       </p>
+         </p>
+       </div>
+
+      <aside class="example" data-transform="updateExample" title="Convenience Context">
+        <p>Code of the <a>convenience context</a>. Available as:
+          <a href="https://yaml-ld.dev/context">https://yaml-ld.dev/context</a>.
+        </p>
+        <pre class="json" data-include="code/context.json" data-include-format="text"></pre>
+      </aside>
+
+      <p>The convenience context contains an alias to every JSON-LD keyword which can be aliased as per JSON-LD 1.1
+        specification, — which means all the keywords except <code>@context</code>. The reserved `@` character is
+        replaced by `$`, which is not reserved and therefore does not require quoting. Consider
+        <strong>Example 1</strong> reformatted using the convenience context:</p>
+
+      <aside class="example" data-transform="updateExample" title="Example YAML-LD document with Convenience Context">
+        <pre class="yaml" data-include="code/with-convenience-context.yaml" data-include-format="text"></pre>
+      </aside>
+
+      <p>The applicability of this context depends on the domain and is left to the architect's best judgement.</p>
+  </section>
+
  </body>
 </html>