Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two + useful thoughts.
+ ++ Follow JSON-LD best practices + …in order to achieve a greater level of reusability, performance, and human friendliness among YAML-LD aware + systems. The [[json-ld-bp]] document is as relevant to YAML-LD as it is to [[JSON-LD]]. +
++ Do not force users to author contexts + + Instead, provide pre-built contexts that the user can reference by URL for a majority of common use cases. +
+YAML-LD is intended to simplify the 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, + and 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 author such a context would make the domain expert's job much + harder — which we, as system architects and developers, should try to avoid.
+ ++ Use a default context +
+ + 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. +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.
+ ++ Alias JSON-LD keywords + + If possible, map JSON-LD keywords containing the `@` character to keywords that do not contain it. +
+The `@` character is reserved in [[YAML]], and thus requires quoting (or escaping), as in the following + example:
+ + + +The need to quote these keywords has to be learnt, and introduces one more little irregularity to the document + author's life. Further, on most keyboard layouts, typing quotes will require `Shift`, which reduces typing speed, + albeit slightly.
+ +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.
+ ++ Use YAML-LD Convenience Context +
YAML-LD users may use a JSON-LD context provided as part of this specification, henceforth known as the + convenience + context, which defines a standardized mapping of every `@`-keyword to a `$`-keyword, except `@context`. +
+ +The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1
+ specification permits aliasing — which means all the keywords except @context. The reserved `@` character is
+ replaced by `$`, which is not reserved and therefore does not require quoting. Consider
+ Example 1 reformatted using the convenience context:
The applicability of this context depends on the domain and is left to the architect's best judgement.
+